Interested in working with us? We offer a superb REMOTE work opportunity for a DEVOP.

Click here to find out more.

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.

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.

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,
            "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)
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,
            "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,
            "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,
            "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.
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.