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 ofProgram
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 ofClip
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 ofPlaylist
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 ofClip
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
---
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 isJSON
). Valid parameters are:SubRip
,WebVTT
,Text
,TextWithTimestamps
andJSON
. - (Optional)
speakers
Whether a transcript will include speaker names – or default speaker names if speaker names haven't been assigned (default istrue
). Valid parameters aretrue
andfalse
.
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. Thesize
parameter specifies the image size (default size is medium). Valid size parameters are:thumbnail
(64x64),small
(256x256),medium
(600x600) andlarge
(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 formathttps://twitter.com/{SocialTwitter}
).SocialFacebook
(string) The Facebook page username of the program (should be accessed in the formathttps://fb.com/{SocialFacebook}
).Hidden
(boolean) Iftrue
, 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) Iftrue
, 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. Thesize
parameter specifies the image size (default size is medium). Valid size parameters are:thumbnail
(64x64),small
(256x256),medium
(600x600) andlarge
(3000x3000).NumberOfClips
(number) The number of clips available in the playlistVisibility
(string) The visibility of the clip. Valid values arePublic
,Unlisted
andPrivate
.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 areFull
,Trailer
andBonus
.ImageUrl
(string) A publicly-accessible URL to the artwork image for this clip. Thesize
parameter specifies the image size (default size is medium). Valid size parameters are:thumbnail
(64x64),small
(256x256),medium
(600x600) andlarge
(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 ofPublished
.PublishedUrl
(string) A publicly-accessible URL for the clip's Omny.fm web playerVisibility
(string) The visibility state of the clip. Valid visibilities arePublic
(should be publicly shown in directories and indexes), andUnlisted
(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 areUnrated
,Clean
andExplicit
.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 inhh: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.