Consumer API

Omny Studio’s consumer APIs allows third-parties to integrate metadata about published content in custom players and content directories on a website or in a mobile app.

Only publicly-published content will be available in the consumer API. Hidden programs, private clips or private playlists will not be accessible.

Note: the “consumer API” is a read-only API. To create, edit or delete content, the “management API” allows private administrative access to the organization.

Analytics

If you'd like to track the number of plays/downloads that are occurring from your custom players, you can define and track custom sources.

If you'd like to track consumption data for plays on custom players, you can send player events using the Omny Studio's consumption analytics API.

Caching

Responses are cached up to 10 minutes. Updates to clip metadata may not be reflected until the cache is refreshed.

CORS

For optimal API performance, we recommend making "simple requests" (i.e. do not specify any custom HTTP headers) to avoid triggering a CORS OPTIONS preflight request.

Rate limits

There are no practical rate limits to this API. However, our web application firewall Cloudflare may block traffic it deems to be malicious or harmful.

Disable preloading

We recommend third-party publishers who build custom players to disable preloading and auto-playing from their players to ensure only user-initiated playback will trigger a download.

---

Programs

Get the programs for an Omny Studio organization.

Request

GET https://omny.fm/api/orgs/{orgId}/programs/

Parameters

orgId The ID of the Omny Studio organization.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/programs/

Model

Programs The response is an array of Program objects (schema defined below).

---

Program details

Get the metadata for an Omny Studio program.

Request

GET https://omny.fm/api/orgs/{orgId}/programs/{programId}

Parameters

orgId The ID of the Omny Studio organization.
programId The ID of the Omny Studio program.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/programs/8ac9406d-304d-441e-8532-a4ba00967cfc

Model

The response is a Program object (schema defined below).

---

Program clips

Get the clips for an Omny Studio program. Only publicly-listed clips (public) are shown; unlisted or private clips won't appear in the response.

Request

GET https://omny.fm/api/orgs/{orgId}/programs/{programId}/clips

Parameters

orgId The ID of the Omny Studio organization.
programId The ID of the Omny Studio program.
(Optional) cursor The paging cursor value to use in order to fetch the next page.
(Optional) pageSize The number of clips to return in one page.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/programs/8ac9406d-304d-441e-8532-a4ba00967cfc/clips

Model

Clips The response is an array of Clip objects (schema defined below).
Cursor The paging cursor to fetch the next page of clips.

---

Program playlists

Get the playlists for an Omny Studio program. Only publicly-listed playlists (public) are shown; unlisted or private playlists won't appear in the response.

Request

GET https://omny.fm/api/orgs/{orgId}/programs/{programId}/playlists

Parameters

orgId The ID of the Omny Studio organization.
programId The ID of the Omny Studio program.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/programs/8ac9406d-304d-441e-8532-a4ba00967cfc/playlists

Model

Playlists The response is an array of Playlist objects (schema defined below).

---

Playlist details

Get the metadata for an Omny Studio playlist (which can also be considered a podcast).

Request

GET https://omny.fm/api/orgs/{orgId}/playlists/{playlistId}

Parameters

orgId The ID of the Omny Studio organization.
playlistId The ID of the Omny Studio playlist.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/playlists/aa8754a4-90a4-4080-9448-a4ba00a88ed7

Model

The response is a Playlist object (schema defined below).

Alternative URL

If you have an Omny.fm share page URL or an embed URL, you can modify the path to /shows/{programSlug}/playlists/{playlistSlug}.json to be automatically redirected to the playlist details JSON.

Example

https://omny.fm/shows/fun-kids/playlists/lazy-town-on-fun-kids.json

---

Playlist clips

Get the clips for an Omny Studio playlist. Only publicly-available clips in the playlist (public & unlisted) are shown; private clips won't appear in the response.

Request

GET https://omny.fm/api/orgs/{orgId}/playlists/{playlistId}/clips

Parameters

orgId The ID of the Omny Studio organization.
playlistId The ID of the Omny Studio playlist.
(Optional) cursor The paging cursor value to use in order to fetch the next page.
(Optional) pageSize The number of clips to return in one page.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/playlists/aa8754a4-90a4-4080-9448-a4ba00a88ed7/clips

Model

Clips The response is an array of Clip objects (schema defined below).
Cursor The paging cursor to fetch the next page of clips.

---

Clip details

Get the metadata for an Omny Studio clip (episode).

Request

GET https://omny.fm/api/orgs/{orgId}/clips/{clipId}

Parameters

orgId The ID of the Omny Studio organization.
clipId The ID of the Omny Studio clip.

Response

Example

https://omny.fm/api/orgs/289ceca7-bef3-48af-9f74-a4ba0095cab1/clips/b61cd5d4-886f-4f9f-9813-aafe00e55fdb

Model

The response is a Clip object (schema defined below).

Alternative URL

If you have an Omny.fm share page URL or an embed URL, you can modify the path to /shows/{programSlug}/{clipSlug}.json to be automatically redirected to the clip details JSON.

Example

https://omny.fm/shows/fun-kids/kaye-umansky-author-of-witch-in-winter-chats-to-be.json

---

Clip details (by external ID)

Get the metadata for an Omny Studio clip (episode) by external ID.

Request

GET https://omny.fm/api/orgs/{orgId}/clips/externalId?value={externalId}

Parameters

orgId The ID of the Omny Studio organization.
externalId The external ID of the Omny Studio clip (URL encoded).

Response

As above.

---

Clip transcript

Get the transcript for an Omny Studio clip (episode).

Request

GET https://omny.fm/api/orgs/{orgId}/clips/{clipId}/transcript

Parameters

orgId The ID of the Omny Studio organization.
clipId The ID of the Omny Studio clip.
(Optional) format The format in which the transcript will be exported (default is JSON ). Valid parameters are: SubRip, WebVTT, Text, TextWithTimestamps and JSON.
(Optional) speakers Whether a transcript will include speaker names – or default speaker names if speaker names haven't been assigned (default is true). Valid parameters are true and false.

Response

Example

https://omny.fm/api/orgs/ec561129-d0bd-4e28-99b0-a4ff00357c00/clips/e6dec256-6f49-4da0-b419-a96a004fba87/transcript

Model

The response is a file that corresponds to the format parameter. Either a SubRip, WebVTT, Text, Text (with timestamps) or JSON file.

Alternative URL

If you have an Omny.fm share page URL or an embed URL, you can modify the path to /shows/{programSlug}/{clipSlug}/transcript to be automatically redirected to the transcript JSON.

Example

https://omny.fm/shows/omny-website/example-clip/transcript

---

Model schemata

Program

Id (string) The ID of the program.
Name (string) The name of the program.
Slug (string) The URL slug of the program. The Omny.fm show page can be accessed in the format https://omny.fm/shows/{Slug}.
Description (string) The description of the program (plaintext).
DescriptionHtml (string) The description of the program (HTML).
Publisher (string) Deprecated - use Copyright.
Copyright (string) The copyright included in the program's playlist's RSS feeds.
Language (string) The program language (IETF language tag).
ArtworkUrl (string) A publicly-accessible URL to the artwork image for this program. The size parameter specifies the image size (default size is medium). Valid size parameters are: thumbnail (64x64), small (256x256), medium (600x600) and large (3000x3000).
Category (string) Deprecated - use Categories.
Categories (string[]) The list of iTunes category names.
SocialWeb (string) The web URL of the program.
SocialTwitter (string) The Twitter account username of the program (should be accessed in the format https://twitter.com/{SocialTwitter}).
SocialFacebook (string) The Facebook page username of the program (should be accessed in the format https://fb.com/{SocialFacebook}).
Hidden (boolean) If true, the program should be considered "private" and should not be shown in public directories or indexed. (Private programs are not available in the consumer API).
Archived (boolean) If true, the program should be considered an archive and will not be actively updated.
Network (string) Obsolete - use NetworkId.
NetworkId (string) The ID of the network to which the program belongs.
ExternalId (string) An optional ID for mapping this program to an entry in an external system.
ContactName (string) The contact name included in the program's playlist's RSS feeds.
ContactEmail (string) The contact email included in the program's playlist's RSS feeds.
DefaultPlaylistId (string) ID of the default playlist for this program.

Playlist

Id (string) The ID of the playlist.
Title (string) The name of the playlist.
Description (string) The description of the playlist.
ProgramId (string) The ID of the program to which the playlist belongs.
RssFeedUrl (string) The RSS feed URL for this playlist.
EmbedUrl (string) The embed player iframe URL for this playlist.
ArtworkUrl (string) A publicly-accessible URL to the artwork image for this playlist. The size parameter specifies the image size (default size is medium). Valid size parameters are: thumbnail (64x64), small (256x256), medium (600x600) and large (3000x3000).
NumberOfClips (number) The number of clips available in the playlist
Visibility (string) The visibility of the clip. Valid values are Public, Unlisted and Private.
Categories (string[]) The list of iTunes category names.
DirectoryLinks (DirectoryLinks) The podcast directory (Apple Podcasts, Google Podcasts, Spotify) URLs for this playlist.

DirectoryLinks

ApplePodcasts (string) The Apple Podcasts directory URL.
GooglePodcasts (string) The Google Podcasts directory URL.
Spotify (string) The Spotify directory URL.
Stitcher (string) The Stitcher directory URL.
TuneIn (string) The TuneIn directory URL.
GooglePlay (string, obsolete) The Google Play directory URL.
RssFeed (string) The RSS feed URL for this playlist.

Clip

Title (string) The title of the clip.
Description (string) The description of the clip (without any HTML formatting).
DescriptionHtml (string) The description of the clip (with HTML formatting).
Tags (string[]) An array of tags of the clips.
Season (number) An optional season number for the clip (as defined by Apple Podcasts).
Episode (number) An optional episode number for the clip (as defined by Apple Podcasts).
EpisodeType (string) The type of episode of the clip (as defined by Apple Podcasts). Valid values are Full, Trailer and Bonus.
ImageUrl (string) A publicly-accessible URL to the artwork image for this clip. The size parameter specifies the image size (default size is medium). Valid size parameters are: thumbnail (64x64), small (256x256), medium (600x600) and large (3000x3000).
AudioUrl (string) A publicly-accessible URL to the MP3 audio for this clip.
VideoUrl (string) Deprecated - will always be null.
EmbedUrl (string) The embed player iframe URL for this clip.
DurationSeconds (number) The time length of the clip in seconds.
PublishState (string) The publish state of the clip. Clips should have a state of Published.
PublishedUrl (string) A publicly-accessible URL for the clip's Omny.fm web player
Visibility (string) The visibility state of the clip. Valid visibilities are Public (should be publicly shown in directories and indexes), and Unlisted (should not be shown in directories and indexes).
PublishedUtc (string) The date and time when the clip was published.
PlaylistIds (string[]) An array of IDs for playlists to which the clip has been added.
Chapters (ClipChapter[]) An array of chapter objects added to the clip.
State (string) The state of the clip. Valid states are: Ready (the clip is ready to be played).
ShareUrl (string) An optional override for the share URL.
ImportId (string) An optional episode identifier if the clip was imported from another provider.
Monetization (ClipMonetization) Monetization settings for the clip.
RecordingMetadata (RecordingMetadata) Related information about the recording associated with the clip if made from a recording.
ProgramId (string) The ID of the program the to which the clip belongs.
PublishedAudioSizeInBytes (number) If the clip is published, the size of the audio file in bytes.
ContentRating (string) The content rating of the of the clip. Valid ratings are Unrated, Clean and Explicit.
ExternalId (string) The external ID of the clip.
CustomFieldData ({string: string}) Data for the Custom fields for this clip.

ClipChapter

Id (string) The ID of the chapter.
Name (string) The name of the chapter.
Position (string) The timestamp of the chapter in hh:mm:ss.

ClipMonetization

PreRoll (boolean) If pre-roll ad is enabled for this clip.
PostRoll (boolean) If post-roll ad is enabled for this clip.
MidRolls (TimeSpan[]) An array of midroll locations.
For example, a value of ["00:00:30", "01:23:45"] would represent a midroll at 30 seconds, and one at 1 hour, 23 minutes and 45 seconds into the episode.

RecordingMetadata

CaptureStartUtc (string) The date and time the recording started capturing.
CaptureEndUtc (string) The date and time the recording finished capturing.