Simplecast.fm API Documentation

The Simplecast API is here to help automate some of your podcast-related tasks. It's currently in read-only mode, so you won't be able to update podcasts or episodes, but that might be coming in the future.

Hey, important information! The Simplecast API is currently a work in progress. Things are still in flux, but you're more than welcome to check it out and provide feedback. It shouldn't change too much, but we can't guarantee we won't break it.


Endpoint URL

The Simplecast API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We require using SSL encryption by issuing requests through HTTPS.

https://api.simplecast.com/v1/

Authentication

All requests must be authenticated using your API key, available in your Simplecast account settings. You have the option of authenticating one of three different ways: using HTTP Basic Auth, passing it as a request parameter, or setting an HTTP header. Your API key is available in your Simplecast account settings.

HTTP Basic Auth (username only)
curl https://api.simplecast.com/v1/podcasts.json -u YOUR_API_KEY:

Request Parameter
curl https://api.simplecast.com/v1/podcasts.json?api_key=YOUR_API_KEY

HTTP Header
curl --header "X-API-KEY: YOUR_API_KEY" https://api.simplecast.com/v1/podcasts.json

HTTP Response Codes

200 Everything is OK
401 Authentication failed
404 Resource not found
500 Internal server error

Podcasts

Retrieve a list of all the podcasts you own or manage, or retrieve a single podcast.

GET /podcasts.json

Request

curl https://api.simplecast.com/v1/podcasts.json -u YOUR_API_KEY:

Response

TBD

GET /podcasts/{PODCAST_ID}.json

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}.json -u YOUR_API_KEY:

Response

TBD


Episodes

Retrieve a list of podcast episodes, or information for a single episode.

GET /podcasts/{PODCAST_ID}/episodes.json

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/episodes.json -u YOUR_API_KEY:

Response

TBD

GET /podcasts/{PODCAST_ID}/episodes/{EPISODE_ID}.json

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/episodes/{EPISODE_ID}.json -u YOUR_API_KEY:

Response

TBD


Player Embeds

HTML for embedding an episode into another web page.

GET /podcasts/{PODCAST_ID}/episodes/{EPISODE_ID}/embed.json

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/episodes/{EPISODE_ID}/embed.json -u YOUR_API_KEY:

Response

TBD


Statistics

Listener statistics for a podcast or episode.

GET /podcasts/{PODCAST_ID}/statistics.json

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/statistics.json -u YOUR_API_KEY:

Response

TBD

GET /podcasts/{PODCAST_ID}/statistics/overall.json
Querystring Parameters
timeframe string options: recent (default), year, all, custom
start_date YYYY-MM-DD required for 'custom' timeframe
end_date YYYY-MM-DD defaults to today

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/statistics/overall.json -u YOUR_API_KEY:

Response

TBD

GET /podcasts/{PODCAST_ID}/statistics/episode.json
Querystring Parameters
episode_id integer ID of the episode you're requesting statistics for
timeframe string options: recent (default), year, all, custom
start_date YYYY-MM-DD required for 'custom' timeframe
end_date YYYY-MM-DD defaults to today

Request

curl https://api.simplecast.com/v1/podcasts/{PODCAST_ID}/statistics/episode.json?episode_id={EPISODE_ID} -u YOUR_API_KEY:

Response

TBD