API: Episodes

In this page

The Episode object

An Episode is an audio track that can be listened to. It can be recorded or broadcasted live, and always belongs to a Show. An episode could be a podcast episode, a music track or song, a radio show episode, or a live broadcast.

An episode has several properties. Each API can return an Episode model all those properties, or just a subset. All the properties are listed here:

Property	Type	Description
`episode_id`	Numeric	Unique episode identifier
`type`	String	The episode type. It could be `DRAFT`, `RECORDED`, `LIVE` or `EXTERNAL`
`title`	String	Episode title
`description`	String	Episode description
`duration`	Numeric	Episode duration expressed in milliseconds
`site_url`	String	Public URL of the episode on Spreaker’s website
`image_original_url`	String	Original size image URL
`image_url`	String	200x200px size image URL
`published_at`	String	The date/time on which this episode has been published
`auto_published_at`	String	The date/time on which this episode has been scheduled to be published later
`author`	User	The author/owner of the episode
`author_id`	Numeric	User ID of the episode author
`show`	Show	The show the episode belongs to
`show_id`	Numeric	Show ID of the show this episodes belongs to
`download_enabled`	Boolean	`true` if the author allowed this episode to be downloaded, otherwise `false`
`plays_count`	Numeric	The number of overall plays of this episode
`downloads_count`	Numeric	The number of overall downloads of this episode
`likes_count`	Numeric	The number of overall likes of this episode
`messages_count`	Numeric	The number of overall messages of this episode
`is_on_air`	Boolean	This property is exported only on `LIVE` episodes. The value is `true` if the episode’s live stream is currently active (broadcasting), otherwise it’s `false`
`is_non_stop`	Boolean	This property is exported only on `LIVE` episodes. The value is `true` if the episode live stream is 24/7 (non stop), otherwise it’s `false`
`encoding_status`	String	The episode’s status, whether it’s either processing or encoding. The episode can be listened to only when the `encoding_status` is `READY`.
`waveform_url`	String	URL of the episode’s waveform data points (see Displaying the Episode Waveform for more information). The value is `null` if the episode has no waveform (ie. `LIVE` episodes or `DRAFT` episodes without any media file yet).
`tags`	Array	List of tags/keywords related to the content.
`hidden`	Boolean	Whether the episode is accessible publicly, either on website or RSS feeds.
`visibility`	String	The specific visibility status of the episode. It could be `PUBLIC`, `PRIVATE` or `LIMITED`.
`site_limited_url`	String	The site link that gives access to a `LIMITED` episode. This is generated when the `visibility` of an episode is changed to `LIMITED`. `LIMITED` episodes are not listed on the website or RSS feeds.
`site_limited_key`	String	The episode private key that provides access to the episode.
`media_id`	Numeric	The ID of the episode media
`media_url`	String	URL of the episode’s media. The value is `null` if the episode has no media or media is not available (ie. `LIVE` episodes or `DRAFT` episodes without any media file yet).

The type field can have the following values:

LIVE: the episode is currently LIVE. By playing this episode you’ll be able to listen directly to its live stream. The duration field could be absent or null, because the duration of a live episode is unknown.
RECORDED: the episode has been uploaded, or it was once a LIVE episode that ended and has been archived. You can safely read and display the duration field.
EXTERNAL: the episode is not hosted on Spreaker, but on a 3rd party and is available to be listened to. You can safely read and display the duration field. This type of episode cannot be created via APIs.
DRAFT: the episode is in a draft state and has not been published yet. In this state, the episode could have no audio file associated with it yet: once it does have an audio file, it can be immediately published by setting published_at, or scheduled to be published later by setting auto_published_at (in both cases the type will switch to RECORDED).

The encoding_status field can have the following values:

PENDING: the episode is in queue and waiting to be processed or it has no audio file yet (see Working with draft episodes).
PROCESSING: the episode is currently processing. This operation could take a while, depending on the episode’s duration.
READY: the episode has been successfully processed and is ready to be listened to.
ERROR: an error occurred while processing the episode.

The visibility field can have the following values:

PUBLIC: the episode is publicly accessible through Website, Widget, Apps and on RSS feed.
PRIVATE: the episode is not accessible in any platform in a public way. Only the owner of the episode can see it.
LIMITED: the episode is accessible on the Website through a special url and in the Widget using the following query parameter episode_key=<SITE_LIMITED_KEY>

Retrieving a Single Episode

GET /v2/episodes/EPISODE-ID

The returned Episode contains most of all its public information, from its title and description, to its author (a User model) and its show (a Show model).

Example

curl https://api.spreaker.com/v2/episodes/7760317

The response body is a JSON object containing all the episodes fields (plus the author and show public fields).

{
    "response": {
        "episode": {
            "episode_id": 7760317,
            "type": "RECORDED",
            "title": "SLS45: Music in Podcasts, Aaron Roden, Air-Raid Podcast",
            "duration": 2240180,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/7760317",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-02-10 23:00:40",
            "download_enabled": true,
            "description": "Spreaker Live Show #45 for Feb 10th, 2016",
            "created_at": "2016-02-10 23:00:40",
            "plays_count": 125,
            "downloads_count": 90,
            "likes_count": 4,
            "messages_count": 9,
            "visibility": "PUBLIC",
            "author": {
                "user_id": 8114541,
                "fullname": "Spreaker Live Show",
                "site_url": "https://www.spreaker.com/user/spreakerliveevents",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/da9b085ab425d819e5de6f978487a487.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/da9b085ab425d819e5de6f978487a487.jpg"
            },
            "show": {
                "show_id": 1433865,
                "title": "Spreaker Live Show with Rob Greenlee",
                "site_url": "https://www.spreaker.com/show/spreaker-live-show",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "author_id": 8114541
            }
        }
    }
}

Updating an Episode

POST /v2/episodes/EPISODE-ID

Authenticated: yes. Owner: yes

The API POST /v2/episodes/EPISODE-ID supports these parameters, none of which are required, as you should specify only the ones you want to update:

Parameter	Type	Description
`title`	String	Max length: 140
`description`	String	-
`show_id`	Numeric	The unique show ID that this episode belongs to. Changing this value means moving the episode to another show.
`explicit`	Boolean	`true` if the episode contains explicit content (defaults to `false`)
`download_enabled`	Boolean	`true` if the episode can be downloaded (defaults to `true`)
`hidden`	Boolean	`true` if the episode should not be visible on public pages and listings (defaults to `false`)
`visibility`	String	The specific visibility status of the episode. It could be `PUBLIC`, `PRIVATE` or `LIMITED`. If the `LIMITED` visibility is set but it’s not available, `PRIVATE` will be used instead.
`tags`	String	Comma-separated list of tags/keywords related to the content. Adding tags improves searchability.
`autopermalink`	Boolean	`true` to automatically generate a unique permalink based on the episode’s title (defaults to `false`)
`permalink`	String	Allows you to change the episode’s permalink (keeping it unchanged if not provided). The provided permalink must be unique across the owner’s episodes.
`location_latitude`	Numeric	Latitude of the GPS coordinates related to this episode
`location_longitude`	Numeric	Longitude of the GPS coordinates related to this episode
`image_file`	File	At least 400x400, Max size: 5MB, Formats: JPG, PNG
`image_crop`	String	Comma-separated coordinates (top left X, top left Y, bottom right X, bottom right Y) used to crop an `image_file`. If not specified, the `image_file` will not be cropped. This parameter is effective only if the request contains an `image_file`.
`published_at`	String	The date/time when the episode was published. It can be edited only for `RECORDED` episodes.
`auto_published_at`	String	The date/time when the episode has been scheduled to be published (as in published at a later date/time). If the episode has been scheduled to be published later, it can be edited by changing the date / time it will be published or by setting an empty string to switch it back to an “unscheduled” state.
`media_file`	File	The audio file that should be associated with this episode. You can use this API to both upload a `media_file` for the first time, or replace the `media_file` associated with an episode that already has one.
`chapters`	String	JSON-encoded array of chapters that should be associated with this episode. Chapters are a sort of bookmarks for your episode and are mainly used to give listeners an easy way to fast forward to certain topics within your episode. See Uploading an Episode with Chapters for more information about the format.
`autoshares`	String	Enable auto-sharing to social networks. The value can be a comma separated list of values: `FACEBOOK`, `TWITTER`, `SOUNDCLOUD`, `TUMBLR`, `YOUTUBE`. Auto-sharing can be configured only on non published episodes and it’s required your account to be connected to the respective social network in order to work.
`ihr_publish`	Boolean	If `false` the episode will not be published on iHeart (defaults to `true`). This option is ignored if the episode’s show has not been submitted and approved for publishing on iHeart. Please, see Publishing an episode to iHeart for more information.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Title" https://api.spreaker.com/v2/episodes/12345678

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 77180,
            "type": "RECORDED",
            "title": "Title",
            "duration": 193698,
            "show_id": 1,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/77180",
            "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/1ab1c553452369f36344fd84a55ef837.jpg",
            "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/1ab1c553452369f36344fd84a55ef837.jpg",
            "published_at": "2016-02-07 13:54:54",
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "i-love-coldplay",
            "plays_count": 0,
            "downloads_count": 1,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 1,
                "title": "rgsdfgaaaaasdfgsfg",
                "site_url": "https://www.spreaker.com/show/aaaaa_5",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/1ab1c553452369f36344fd84a55ef837.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/1ab1c553452369f36344fd84a55ef837.jpg",
                "author_id": 1
            },
            "segments": [{
                "type": "audio_ad",
                "target": {
                    "content_category": "finance",
                    "content_safe": "false",
                    "content_explicit": "false"
                }
            }, {
                "type": "episode",
                "http_url": "https://d1kuc8t06fl24.cloudfront.net/episodes/high/3099.mp3",
                "http_url_expires_at": "2016-04-20 15:03:57"
            }],
            "tags": [],
            "encoding_status": "READY",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-02-07 13:54:54",
            "updated_at": "2016-04-18 15:03:57"
        }
    }
}

Deleting an Episode

DELETE /v2/episodes/EPISODE-ID

Authenticated: yes

Delete a particular episode. This requires the request to be authenticated with the episode’s author credentials.

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/episodes/7912694

Downloading an Episode

Authenticated: optional

GET /v2/episodes/EPISODE-ID/download

GET /v2/episodes/EPISODE-ID/download.mp3

Downloads a particular episode. This action is only available on episodes with download_enabled set to true or if the request is authenticated as the owner of the content. The application_id parameter is optional.

Parameter	Type	Description
`application_id`	Numeric	Your application’s ID, if you want the download attributed to it.

Example

curl https://api.spreaker.com/v2/episodes/7760317/download

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/EPISODE-ID/download"

Playing an Episode

GET /v2/episodes/EPISODE-ID/play

GET /v2/episodes/EPISODE-ID/play.mp3

Plays/streams a particular episode. The application_id parameter is optional.

Parameter	Type	Description
`application_id`	Numeric	Your application’s ID, if you want the play attributed to it.

Example

curl https://api.spreaker.com/v2/episodes/7760317/play

Uploading a Recorded Episode

POST /v2/shows/SHOW-ID/episodes

Authenticated: yes. Owner: yes

The API POST /v2/shows/SHOW-ID/episodes creates a new RECORDED episode with the uploaded media_file audio file. The request must be authenticated with the SHOW-ID’s owner credentials.

The only required parameters are the title and media_file: all other parameters are optional and can be edited later. Check out the Upload an Episode guide to get more information and working examples.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Daily News" https://api.spreaker.com/v2/shows/1/episodes

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 129229,
            "type": "RECORDED",
            "title": "Daily News",
            "duration": 256104,
            "show_id": 64,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/129229",
            "image_url": null,
            "image_original_url": null,
            "published_at": "2016-07-04 09:51:57",
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "daily-news_5",
            "plays_count": 0,
            "downloads_count": 0,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 64,
                "title": "La bamba",
                "site_url": "https://www.spreaker.com/show/la-bamba",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/b91c2eac2986522f7ab1e5904768407f.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/b91c2eac2986522f7ab1e5904768407f.jpg",
                "author_id": 1
            },
            "segments": [{
                "type": "episode",
                "http_url": "https://d1kuc8t06fl24.cloudfront.net/episodes/high/6093.mp3",
                "http_url_expires_at": "2016-07-06 09:51:57"
            }],
            "tags": [],
            "media_id": 6093,
            "media_url": "http://d1xg9iidblidzv.cloudfront.net/episodes/original/6093",
            "encoding_status": "READY",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-07-04 09:51:57",
            "updated_at": "2016-07-04 09:51:57"
        }
    }
}

Creating a Draft Episode

POST /v2/episodes/drafts

Authenticated: yes.

The API POST /v2/episodes/drafts creates a new DRAFT episode and supports all the parameters of the Updating an Episode API.

The only required parameters are the title and show_id: all other parameters are optional and can be edited later. Check out the working with draft episodes guide to get more details about draft episodes.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Daily News" -F "show_id=SHOW-ID" https://api.spreaker.com/v2/episodes/drafts

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 101067,
            "type": "DRAFT",
            "title": "Daily News",
            "duration": null,
            "show_id": 64,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/101067",
            "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
            "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
            "published_at": null,
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "daily-news_4",
            "plays_count": 0,
            "downloads_count": 0,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 64,
                "title": "La bamba",
                "site_url": "https://www.spreaker.com/show/la-bamba",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
                "author_id": 1
            },
            "segments": [],
            "tags": [],
            "media_id": null,
            "encoding_status": "PENDING",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-04-28 09:01:16",
            "updated_at": "2016-04-28 09:01:16"
        }
    }
}

Retrieving a User’s Episodes

GET /v2/users/USER-ID/episodes

This API returns a paginated list of Episodes that belong to a USER-ID. Each has just a subset of Episode properties.

Parameter	Type	Description
`filter`	String	Filter episodes by `listenable` or `editable` (defaults to `listenable`). If you specify `filter=editable` the request must be authenticated with the `USER-ID`’s owner credentials.
`direction`	String	Scans episodes `forward` or `backward` according to their natural order (defaults to `forward`). If you specify `direction=backward` the request must also include `last_id`.

Example

curl https://api.spreaker.com/v2/users/8114541/episodes?limit=3

The response body is a paginated list of Episodes.

{
    "response": {
        "items": [{
            "episode_id": 8937153,
            "type": "RECORDED",
            "title": "SLSPM70: Rob Cesternino, Host of Rob Has A Podcast, Post Show Recaps",
            "duration": 1166160,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8937153",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-07 17:13:41",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8937153.gz.json?v=j1qecT"
        }, {
            "episode_id": 8936994,
            "type": "RECORDED",
            "title": "SLSPM69: Marty Michael, Co-Founder of HeadGum Podcast Network",
            "duration": 1460430,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8936994",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-07 16:47:54",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8936994.gz.json?v=2fAdf6"
        }, {
            "episode_id": 8929762,
            "type": "RECORDED",
            "title": "SLSPM67: Rob McCracken, Director of Digital Solutions Group at Scripps Media/Midroll Media/Stitcher",
            "duration": 1866890,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8929762",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-06 17:38:16",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8929762.gz.json?v=AadaWY"
        }],
        "next_url": "https://api.spreaker.com/v2/users/8114541/episodes?filter=listenable&last_id=8929762&limit=3"
    }
}

Retrieving a Show’s Episodes

GET /v2/shows/SHOW-ID/episodes

This API returns a paginated list of Episodes that belong to a SHOW-ID. Each has just a subset of Episode properties.

Parameter	Type	Description
`filter`	String	Filter episodes by `listenable` or `editable` (defaults to `listenable`). If you specify `filter=editable` the request must be authenticated with the `SHOW-ID`’s owner credentials.
`sorting`	String	Sort episodes by `newest` first or `oldest` first (defaults to show’s settings - usually it’s `newest`).
`direction`	String	Scans episodes `forward` or `backward` according to their natural order (defaults to `forward`). If you specify `direction=backward` the request must also include `last_id`.

Example

curl https://api.spreaker.com/v2/shows/1433865/episodes?limit=3

The response body is a paginated list of Episodes.

{
  "response": {
    "items": [{
      "episode_id": 7869337,
      "type": "RECORDED",
      "title": "SLS48: Christian Radio Syndication and Podcasting, Matt Thomas of Know The Truth (KTT.org)",
      "duration": 1911380,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7869337",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-25 20:30:27",
      "download_enabled": true
    }, {
      "episode_id": 7869150,
      "type": "RECORDED",
      "title": "SLS47: Christian Radio to Podcasting, Wayne Shepherd, Radio/Podcast Host",
      "duration": 1648200,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7869150",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-25 20:01:34",
      "download_enabled": true
    }, {
      "episode_id": 7811083,
      "type": "RECORDED",
      "title": "SLS46: Faith-Based Podcasting, Dr. Jerry Johnson, CEO of National Religious Broadcasters",
      "duration": 1522700,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7811083",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-17 23:00:57",
      "download_enabled": true
    }],
    "next_url": "https://api.spreaker.com/v2/shows/1433865/episodes?last_id=7811083&limit=3"
  }
}

Adding an Episode to Likes

PUT /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can add an episode to your Likes list only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X PUT https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object.

{"response":[]}

Removing an Episode from Likes

DELETE /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can remove an episode from Likes only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X DELETE https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object

{"response":[]}

Checking if an User likes an Episode

GET /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters, and return 200 if you like EPISODE-ID, 404 otherwise. You can check Likes only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X GET https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object

{"response":[]}

Retrieving Liked Episodes

GET /v2/users/USER-ID/likes

This API returns a paginated list of Episodes liked by the USER-ID. Each has just a subset of Episode properties.

Example

curl https://api.spreaker.com/v2/users/1/likes?limit=3

The response body is a paginated list of Episodes.

{
    "response": {
        "items": [{
            "episode_id": 7711204,
            "type": "LIVE",
            "title": "FQ Radio - Live",
            "duration": null,
            "show_id": 1632400,
            "author_id": 8587991,
            "site_url": "https://www.spreaker.com/episode/7711204",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/ad931f30150db8bc14409269db81826e.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/ad931f30150db8bc14409269db81826e.jpg",
            "published_at": "2016-02-04 14:05:14",
            "download_enabled": false,
            "is_non_stop": true
        }, {
            "episode_id": 7703522,
            "type": "EXTERNAL",
            "title": "Talking Heads - Psycho Killer",
            "duration": 146290,
            "show_id": 1555199,
            "author_id": 8432030,
            "site_url": "https://www.spreaker.com/episode/7703522",
            "image_url": null,
            "image_original_url": null,
            "published_at": "2016-02-02 10:25:23",
            "download_enabled": true
        }, {
            "episode_id": 7489480,
            "type": "RECORDED",
            "title": "New Year's Eve (w/Chris Radford)",
            "duration": 2494010,
            "show_id": 1607991,
            "author_id": 8457160,
            "site_url": "https://www.spreaker.com/episode/7489480",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a8dfc4f39fcfc24eb783359bfb0b95bd.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a8dfc4f39fcfc24eb783359bfb0b95bd.jpg",
            "published_at": "2016-01-04 11:00:28",
            "download_enabled": true
        }],
        "next_url": "https://api.spreaker.com/v2/users/1/likes?last_id=7489480&limit=3"
    }
}

Retrieving Users that Liked an Episode

GET /v2/episodes/EPISODE-ID/likes

This API returns a paginated list of Users that liked the EPISODE-ID. Each has just a subset of User properties.

Example

https://api.spreaker.com/v2/episodes/7711204/likes?limit=3

The response body is a paginated list of Users.

{
    "response": {
        "items": [{
            "user_id": 8559276,
            "fullname": "Best Hit Radio Dance",
            "site_url": "https://www.spreaker.com/user/8559276",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/97b370923d29db9318666a75f407124a.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/97b370923d29db9318666a75f407124a.jpg"
        }, {
            "user_id": 4696233,
            "fullname": "Gaia Bocelli",
            "site_url": "https://www.spreaker.com/user/4696233",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a0f4aea20d19e2bdc74f9aa4d585f20c.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a0f4aea20d19e2bdc74f9aa4d585f20c.jpg"
        }, {
            "user_id": 4633161,
            "fullname": "Tony R. Williams",
            "site_url": "https://www.spreaker.com/user/4633161",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/780255f43c15c77b8c480e7d6fa90487.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/780255f43c15c77b8c480e7d6fa90487.jpg"
        }],
        "next_url": "https://api.spreaker.com/v2/episodes/7711204/likes?last_id=4633161&limit=3"
    }
}

Adding an Episode to Bookmarks

PUT /v2/users/USER-ID/bookmarks/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can add an episode to bookmarks only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X PUT https://api.spreaker.com/v2/users/123/bookmarks/456

The response body is an empty object

{"response":[]}

Removing an Episode from Bookmarks

DELETE /v2/users/USER-ID/bookmarks/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can remove an episode from bookmarks only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X DELETE https://api.spreaker.com/v2/users/123/bookmarks/456

The response body is an empty object

{"response":[]}

Publishing an episode to YouTube

POST /v2/episodes/EPISODE-ID/youtube

Authenticated: yes

This API requests to publish an episode to YouTube, and requires to be authenticated with the episode’s author credentials. This operation is asynchronous and can take some time: you can poll the API to retrieve the status of the publishing to YouTube, to get updates about the progress.

The response contains the current status of the publishing to YouTube:

{
    "response": {
        "youtube": {
            "status": "PENDING",
            "videos": []
        }
    }
}

Retrieving the status of Episode publishing to YouTube

GET /v2/episodes/EPISODE-ID/youtube

Authenticated: yes

This API returns the current status of an episode publishing to YouTube, and requires to be authenticated with the episode’s author credentials. In particular, this API returns two main information:

status: the current status of the publishing to YouTube
videos: an ordered list of videos that have been generated to upload your episode to YouTube (if was successfully uploaded to YouTube)

{
    "response": {
        "youtube": {
            "status": "UPLOADED_PARTIAL",
            "videos": [{
                "video_title": "My episode (part 1 of 3)",
                "video_id": "1",
                "video_url": "https://www.youtube.com/watch?v=1",
                "video_status": "UPLOADED"
            }, {
                "video_title": "My episode (part 2 of 3)",
                "video_id": null,
                "video_url": null,
                "video_status": "DELETED"
            }, {
                "video_title": "My episode (part 3 of 3)",
                "video_id": "3",
                "video_url": "https://www.youtube.com/watch?v=3",
                "video_status": "UPLOADED"
            }]
        }
    }
}

The status property can have the following values:

Value	Description
`UNPUBLISHED`	The episode has not been published to YouTube.
`PENDING`	The episode has been enqueued for publishing to YouTube.
`DOWNLOADING`	The video generator is downloading the episode audio file.
`PROCESSING`	The video generator is making the video file.
`UPLOADING`	The video generator is uploading the video to YouTube.
`UPLOADED`	The video has been successfully uploaded to YouTube.
`UPLOADED_PARTIAL`	The video generator has splitted your episode into multiple video files (due to the max video duration limit on your YouTube account) and only few videos have been successfully uploaded to YouTube.
`ERROR_AUTH`	The video generator was unable to upload the video on YouTube, due to an authentication error.
`ERROR_DOWNLOAD`	The video generator was unable to make the video, because unable to download the episode audio file.
`ERROR_PROCESSING`	The video generator has encountered an unexpected error while making the video.
`ERROR_UPLOAD`	The video generator was unable to upload the video on YouTube, due to a network error.

The videos property is an array containing one or more videos. For each video you will find the following properties:

video_title: the YouTube video title.
video_id: the YouTube video id (can be null if the video has been removed).
video_url: the YouTube video url (can be null if the video has been removed).
video_status: the status of the video on YouTube (can be null if unable to retrieve it from YouTube).

The video_status property can have the following values:

Value	Description
`DELETED`	The video has been removed.
`ERROR_PROCESSING`	An error occurred while processing the video on YouTube.
`ERROR_REJECTED`	The video has been rejected by YouTube (ie. due to copyright infringement issues).
`UPLOADED`	The video has been successfully uploaded and published to Youtube.
`null`	Spreaker is unable to retrieve the current status of your video on YouTube (ie. the Spreaker account is not more connected to YouTube).

Why Spreaker sometimes split the episode into multiple videos?
YouTube has a limit of the max video duration that depends on your account. This limit is generally 15 minutes if your YouTube account has not been verified, or several hours otherwise. If your episodes get splitted into multiple videos, it means that your YouTube account has not been verified yet.

Publishing an episode to SoundCloud

POST /v2/episodes/EPISODE-ID/soundcloud

Authenticated: yes

This API requests to publish an episode to SoundCloud, and requires to be authenticated with the episode’s author credentials. This operation is asynchronous and can take some time: you can poll the API to retrieve the status of the publishing to SoundCloud, to get updates about the progress.

The response contains the current status of the publishing to SoundCloud:

{
    "response": {
        "soundcloud": {
            "status": "PENDING",
            "track": null
        }
    }
}

Retrieving the status of Episode publishing to SoundCloud

GET /v2/episodes/EPISODE-ID/soundcloud

Authenticated: yes

This API returns the current status of an episode publishing to SoundCloud, and requires to be authenticated with the episode’s author credentials. In particular, this API returns two main information:

status: the current status of the publishing to SoundCloud
track: the SoundCloud track’s metadata if was successfully uploaded to SoundCloud, otherwise null

{
    "response": {
        "soundcloud": {
            "status": "UPLOADED",
            "track": {
                "track_title": "Track title",
                "track_id": 100000,
                "track_url": "https://soundcloud.com/track",
                "track_status": "READY"
            }
        }
    }
}

The status property can have the following values:

Value	Description
`UNPUBLISHED`	The episode has not been published to SoundCloud.
`PENDING`	The episode has been enqueued for publishing to SoundCloud.
`DOWNLOADING`	The publishing tool is downloading the episode audio file.
`UPLOADING`	The publishing tool is uploading the audio to SoundCloud.
`UPLOADED`	The audio track has been successfully uploaded to SoundCloud.
`ERROR_AUTH`	The publishing tool was unable to upload the audio on SoundCloud, due to an authentication error.
`ERROR_DOWNLOAD`	The publishing tool was unable to upload the audio on SoundCloud, because unable to download the episode audio file.
`ERROR_UPLOAD`	The publishing tool was unable to upload the audio on SoundCloud, due to a network error.
`ERROR_QUOTA`	The publishing tool was unable to upload the audio on SoundCloud, because the SoundCloud account has reached the storage limit.
`ERROR_UNVERIFIED`	The publishing tool was unable to upload the audio on SoundCloud, because the SoundCloud account is not verified. Please visit https://soundcloud.com/settings to verify your account.

The track property contains some information about the uploaded SoundCloud track:

track_title: the SoundCloud track title.
track_id: the SoundCloud track id.
track_url: the SoundCloud track url (can be null if unable to retrieve it from SoundCloud).
track_status: the status of the track on SoundCloud (can be null if unable to retrieve it from SoundCloud).

The track_status property can have the following values:

Value	Description
`PROCESSING`	The track has been uploaded to SoundCloud and it’s currently being processed.
`ERROR_PROCESSING`	An error occurred while processing the track on SoundCloud.
`READY`	The track has been successfully uploaded and processed on SoundCloud.
`null`	Spreaker is unable to retrieve the current status of your track on SoundCloud (ie. the Spreaker account is not more connected to SoundCloud).

Publishing an episode to iHeart

POST /v2/episodes/EPISODE-ID/iheart

Authenticated: yes

This API requests to publish an episode to iHeart, and requires to be authenticated with the episode’s author credentials.

To publish an episode to iHeart, it’s required the episode’s show has been submitted and approved to be published on iHeart. We currently don’t provide a public API to submit your shows to iHeart, so you should do it thru the Spreaker CMS (it’s a one-time operation you have to do per each show you want to publish to iHeart).

The response contains the current status of the publishing to iHeart:

{
    "response": {
        "iheart": {
            "ihr_status": "PUBLISHED",
            "ihr_publish": true
        }
    }
}

The iheart property contains two pieces of information:

ihr_status: the current status of publishing to iHeart (can be UNPUBLISHED, PENDING or PUBLISHED). Please note that PUBLISHED means the episode has been successfully submitted for publishing to iHeart, but then it could take some time to display on iHeart apps and website, due to their internal publishing mechanisms.
ihr_publish: this flag explicits your intention. Its value is true if you do want to publish the episode on iHeart, false otherwise.