API Getting Started

Description

The Podigee API is a RESTful JSON API for programmatically managing podcasts, episodes, media uploads, and publishing workflows in Podigee. It is built for automation, integrations, and internal tooling so teams can move faster than “clicking around” in the UI. The Podigee API works globally and is optimized for perfect integration into any kind of automated system.

At a glance

  • Type: REST API (HTTP + JSON)
  • Docs & client format: uses OpenAPI / Swagger
  • Base URL: https://app.podigee.com/api/v1/
  • Auth: API key (Token header) or OAuth 2.0 (Authorization: Bearer …)
  • Primary resources: podcasts, episodes, uploads, productions (encoding)
  • Docs / playground: https://app.podigee.com/api-docs
  • Rate limits: plan-dependent; exceeding returns HTTP 429

TLDR; for devs

Check out https://app.podigee.com/api-docs for full API reference.

What the Podigee API is (and why you’d use it)

The Podigee API (and the Podigee Analytics API) exists to make podcast operations reliable, repeatable, and scalable.

Use it when you want to:

  • Automate publishing workflows (create podcasts, create episodes, update metadata, schedule publishing).
  • Build integrations with CMS or editorial systems (headless CMS, WordPress, custom newsroom tools).
  • Run bulk operations (migrations, mass metadata edits, backfills, reorganization across many shows).
  • Connect internal tools for producers and marketing teams (episode templates, QA checks, batch updates).
  • Upload and encode media programmatically (generate an upload URL, upload to storage, trigger encoding).
  • Sync data into analytics/BI (export structured podcast and episode data into your data warehouse).

In other words: if a workflow is repetitive, error-prone, or needs to run at scale, the API is the right interface.

Did you know?

Podigee has an MCP server for analytics, too.

What the Podigee API is not

The Podigee API is not designed to be a public, listener-facing API.

Important usage guidance

  • Do not expose the API directly to listeners (for example: embedding the API key in client-side code or calling the API from a public website).
  • Do not use it as a high-traffic public endpoint without a caching layer or a server-side proxy.
  • Podigee enforces rate limits (requests per minute) that depend on your plan. If you exceed the limit, you will receive HTTP 429 responses and rate-limit details in response headers.
  • If your use case requires higher throughput or a special workflow, contact Podigee support so you can align on a safe approach.

Security note: treat API keys and OAuth tokens like passwords. Store them server-side and rotate them if exposed.

Core concepts (Podigee data model, in plain terms)

Understanding these entities makes the rest of the API predictable:

  • Podcast: the show container (title, language, feeds, settings).
  • Episode: an entry in a podcast feed (title, description, publish time, chapters, etc.).
  • Upload: a temporary, pre-signed URL for uploading a media file to Podigee’s storage.
  • Production: the encoding job created from an uploaded file and linked to an episode.

Typical media workflow (high level):

  1. Create (or identify) the podcast
  2. Create an episode
  3. Generate an upload URL
  4. Upload the media file
  5. Create a production for the episode using the uploaded file URL
  6. Start the production (encoding)
  7. Optionally publish automatically after encoding

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

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles