API Getting Started
Description
The Podigee API allows the automation of publishing processes that would otherwise require manual intervention.
A Word of Caution
Our API provides flexible access to Podigee's data structures and workflows but is not meant to be a listener-facing interface. Please, use the API with care and do not expose it directly to your listeners. Also, do not use it on high-traffic websites without a caching layer. We enforce a rate limit, measured in requests per minute. The rate limit depends directly on the selected plan. If you exceed the rate limit, our API responds with an HTTP 429 status code and some additional information in the headers. In case of doubt, please contact us so that we can discuss further details and give you advice on this matter.
Authentication
Simple API key version
You can find your API key in the account settings if your account allows for it. The key needs to be passed in an HTTP header like this:
curl -H "Token: $apiKey" -H "Content-Type: application/json" https://app.podigee.com/api/v1/podcasts
OAuth version
To use OAuth you need to contact Podigee to receive an App/Client ID, secret and redirect info to use.
In your application you will need to provide a button/link that leads to this URL (replace $my-client-id and $redirect-uri):
Depending on the type of application the user will be redirected back to your site or be presented a temporary authorization code to copy and paste into your application. After that, you need to fetch the actual access token using the authorization code:
curl -X POST -d "client_id=$client_id&client_secret=$client_secret&code=$authorization_code&grant_type=authorization_code&redirect_uri=$redirect_uri" https://app.podigee.com/oauth/token
This returns the actual access token, which then can be used for API calls like this:
curl -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" https://app.podigee.com/api/v1/podcasts
API playground
https://app.podigee.com/api-docs provides interactive documentation of the API to try out.
Examples
Fetch all podcasts
# Request
curl -H "Token: mytoken" -H "Content-Type: application/json" https://app.podigee.com/api/v1/podcasts
# Response
[
{
"id": 42,
"category_id": 1,
"title": "Test",
"subtitle": null,
"description": null,
"quality": "low",
"language": "en",
"authors": null,
"cover_image": null,
"published_at": null,
"created_at": "2015-03-20T19:33:14Z",
"updated_at": "2016-06-05T12:25:25Z",
"feeds": [
{
"format": "mp3",
"url": "http://podcast31889f.podigee.io/feed/mp3"
},
{
"format": "aac",
"url": "http://podcast31889f.podigee.io/feed/aac"
},
{
"format": "opus",
"url": "http://podcast31889f.podigee.io/feed/opus"
},
{
"format": "vorbis",
"url": "http://podcast31889f.podigee.io/feed/vorbis"
}
],
"explicit": null,
"flattr_id": null,
"twitter": null,
"facebook": null,
"copyright_text": null,
"feed_items": 10
},
...
]
Fetch all episodes of a podcast with ID 42
Please note that this only returns a maximum of 50 episodes. To retrieve more episodes please use the limit and offset parameters as documented here.
# Request
curl -H "Token: mytoken" -H "Content-Type: application/json" https://app.podigee.com/api/v1/episodes?podcast_id=42
# Response
[
{
"id": 1,
"guid": "020a3e890ccd0dd99c3e71d61319814f",
"podcast_id": 1,
"production_id": 1,
"title": "New Episode",
"subtitle": "\"Bla\" Blupp Hallo",
"description": null,
"published_at": "2015-03-23T12:20:00Z",
"created_at": "2015-03-20T19:34:05Z",
"updated_at": "2015-03-29T02:12:25Z",
"chapter_marks": [],
"media_clips": [],
"show_notes": null,
"authors": "Test",
"explicit": false,
"cover_image": null
},
...
]
Create a podcast
# Request
curl -H "Token: 123" -H "Content-Type: application/json" -X POST http://www.podigee.dev:4000/api/v1/podcasts -d '{"title": "Test podcast"}'
# Response
{
"id": 42,
"category_id": 1,
"title": "Test",
"subtitle": null,
"description": null,
"quality": "low",
"language": "en",
"authors": null,
"cover_image": null,
"published_at": null,
"created_at": "2015-03-20T19:33:14Z",
"updated_at": "2016-06-05T12:25:25Z",
"feeds": [
{
"format": "mp3",
"url": "http://podcast31889f.podigee.io/feed/mp3"
},
{
"format": "aac",
"url": "http://podcast31889f.podigee.io/feed/aac"
},
{
"format": "opus",
"url": "http://podcast31889f.podigee.io/feed/opus"
},
{
"format": "vorbis",
"url": "http://podcast31889f.podigee.io/feed/vorbis"
}
],
"explicit": null,
"flattr_id": null,
"twitter": null,
"facebook": null,
"copyright_text": null,
"feed_items": 10
}
Create an episode for a podcast with ID 42
# Request
curl -H "Token: mytoken" -H "Content-Type: application/json" -X POST https://app.podigee.com/api/v1/episodes -d '{"title": "Test episode", "podcast_id": 42}'
# Response
{
"id": 1,
"guid": null,
"podcast_id": 42,
"production_id": null,
"title": "Test episode",
"subtitle": null,
"description": null,
"published_at": null,
"created_at": "2016-06-07T16:58:05Z",
"updated_at": "2016-06-07T16:58:05Z",
"chapter_marks": [],
"media_clips": [],
"show_notes": null,
"authors": null,
"explicit": false,
"cover_image": null
}
Upload the audio file
Generate an upload URL
# Request
curl -H "Token: mytoken" -H "Content-Type: application/json" -X POST https://app.podigee.com/api/v1/uploads?filename=episode001.flac
# Response
{
"upload_url": "https://podigee.s3-eu-west-1.amazonaws.com/uploads/u4/test1465315360d448.flac?AWSAccessKeyId=keyId&Expires=1465318879&Signature=sig",
"content_type": "audio/flac",
"file_url": "https://podigee.s3-eu-west-1.amazonaws.com/uploads/u4/test1465315360d448.flac"
}
Use upload_url and content_type to upload the file to our media storage
curl "https://podigee.s3-eu-west-1.amazonaws.com/uploads/u4/test1465315360d448.flac?AWSAccessKeyId=keyId&Expires=1465318879&Signature=sig" --upload-file episode001.flac -H "Content-Type: audio/flac"
Create a production
Use file_url and the episode's id to create a production.
# Request
curl -H "Token: mytoken" -H "Content-Type: application/json" -X POST https://app.podigee.com/api/v1/productions -d '{"episode_id": 1, "files": [{"url": "https://podigee.s3-eu-west-1.amazonaws.com/uploads/u4/test1465315360d448.flac"}]}'
# Response
{
"id": 1,
"episode_id": 1,
"file_url": "https://podigee.s3-eu-west-1.amazonaws.com/uploads/u4/test1465315360d448.flac",
"state": "initial",
"created_at": "2016-06-07T17:04:33Z",
"updated_at": "2016-06-07T17:04:33Z"
}
Start the production to encode the audio file
curl -H "Token: mytoken" -H "Content-Type: application/json" -X PUT https://app.podigee.com/api/v1/productions/1 -d '{"state": "encoding"}'<br>