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.

Caching

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

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/53119a39-8554-4e37-ac12-a4a7000be948/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/53119a39-8554-4e37-ac12-a4a7000be948/programs/9b0b3747-a16b-475f-abce-a4a7000c4553

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

Response

Example

https://omny.fm/api/orgs/53119a39-8554-4e37-ac12-a4a7000be948/programs/9b0b3747-a16b-475f-abce-a4a7000c4553/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/53119a39-8554-4e37-ac12-a4a7000be948/programs/9b0b3747-a16b-475f-abce-a4a7000c4553/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/53119a39-8554-4e37-ac12-a4a7000be948/playlists/72f41252-f59d-44d8-a311-a50d0047167b

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/kinderling-conversation/playlists/podcast.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

Response

Example

https://omny.fm/api/orgs/53119a39-8554-4e37-ac12-a4a7000be948/playlists/72f41252-f59d-44d8-a311-a50d0047167b/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/53119a39-8554-4e37-ac12-a4a7000be948/clips/e70a8bb6-7068-4836-9737-a870001c71f6

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/kinderling-conversation/kinderling-helpline-dream-feeding-temper-tantrums.json

---

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

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.