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 it is not meant to be a listener-facing interface. Please use the API with care and do not expose it directly to your listeners. Do not use it on high-traffic websites without a caching layer. By default, we enforce a hard rate limit of 100 requests/min (responding with a 429 status code and some more 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
If your account allows for it you can find your API key in the account settings. 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 an 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
# 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 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>