The Supercast API provides a RESTful interface to much of the data in the system.
It is used by our official libraries to retrieve episodes, manage subscribers and feeds, act on usage alerts, and more.
If the API is missing something you'd like to see, please let us know.
Version
The Supercast API is versioned in the endpoint path. For example, to use version
"v1" and get all episodes for your channel, you would perform a request to the endpoint
GET /api/v1/episodes. Currently v1 is the only version offered.
Authentication
Authentication is done via access token included as a request header.
curl --header "Authorization: Bearer XXX" https://subdomain.supercast.tech/api/v1/episodes
Where XXX is replace by your access token.
Access tokens
All operations require an access token which can be generated from your channels'
default OAuth2 application.
HTTP responses
The API can return the following HTTP response codes:
| Code | Type | Description |
|---|---|---|
| 200 | OK | Operation was completed successfully |
| 201 | Created | The request has been fulfilled, resulting in the creation of a new resource |
| 400 | Bad Request | The request was malformed and could not be parsed. |
| 401 | Unauthorized | Access token was missing or invalid. |
| 403 | Access denied | Access token does not have the necessary permissions. |
| 404 | Not found | The requested resource was not found. This response will be returned if the URL is entirely invalid (i.e. /asdf), or if it is a URL that could be valid but is referencing something that does not exist (i.e. /episodes/12345). |
| 422 | Unprocessable entity | The request was parseable (i.e. valid JSON), but some parameters were missing or otherwise invalid. |
| 429 | Too many requests | If rate limiting is enabled for your access token, this return code signifies that the rate limit has been reached and the item was not processed. |
Rate Limiting
API usage is throttled to 100 requests per minute from all IP addresses.
Key Endpoints
Most API integrations with Supercast only need to implement 2 endpoints:
- Create a Subscriber to establish Supercast feeds whenever you have a new subscriber
- Delete a Subscriber to revoke access when a membership is cancelled.