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):

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 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>