Group 65Go 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 refreshes.

CORS

For optimal API performance, we recommend making "simple requests" (e.g. 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 malicious or harmful traffic.

---

Programs

Get the programs for an Omny Studio organization

Request

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

Parameters

  • orgId  The GUID 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 GUID of the Omny Studio organization
  • programId The GUID 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 GUID of the Omny Studio organization
  • programId  The GUID 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 GUID of the Omny Studio organization
  • programId  The GUID 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 GUID of the Omny Studio organization
  • playlistId  The GUID 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)

Alternate 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 GUID of the Omny Studio organization
  • playlistId  The GUID 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 GUID of the Omny Studio organization
  • clipId  The GUID 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)

Alternate 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 Transcript

Get the transcript for an Omny Studio clip (episode)

Request

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

Parameters

  • orgId The GUID of the Omny Studio organization
  • clipId The GUID 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 transcripts) or JSON file.

Alternate 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 schema

Program

  • Id  (string) The GUID 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), 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 GUID of the playlist
  • Title  (string) The name of the playlist
  • Description   (string) The description of the playlist
  • ProgramId   (string) The GUID of the program this playlist belongs to
  • 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), large  (3000x3000)
  • NumberOfClips   (number) The number of clips available in the 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), 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 GUIDs for playlists the clip has been added to
  • 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  (RecordingMetata) Related information about the recording associated with the clip if made from a recording.
  • ProgramId  (string) The GUID for the program the clip belongs to
  • 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 GUID 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?