Go to Omny Studio
All Collections
Developer documentation and guidance
Consumer API

Consumer API

Integrate published content and metadata from Omny Studio in web and mobile players
Long Zheng avatar
Written by Long Zheng
Updated over a week ago

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.

If you'd like to track the number of plays/downloads that are occurring from your custom players, you can follow this help guide.

If you'd like to track consumption data for plays which occur on custom players, you can follow this help guide on Omny Studio's consumption analytics API.

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.

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, Cloudflare may block traffic it deems to be malicious or harmful.

---

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.
  • Publisher (string) The publisher of the program.
  • 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) The category of the program.
  • 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) The name of the network group of the 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) If a visualized video has been generated, a publicly-accessible URL to the MP4 video for this clip.
  • 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.

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.
Did this answer your question?