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 called "Token" 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. Please note that we do not provide OAuth Apps for every use case and may request additional workflow descriptions first.

In your application you will need to provide a button/link that leads to this URL (replace $my-client-id and $redirect-uri):

https://app.podigee.com/oauth/authorize?client_id=$my-client-id&redirect_uri=$redirect-uri&response_type=code

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 the   file_url provided in the step before 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 POST https://app.podigee.com/api/v1/productions/1/start

If you want the episode to be published after the encoding is done, you can provide the URL parameter "publish_episode=true".