API Getting Started

Show podcast episodes on your own website or CMS

Use the public RSS feed when your website needs the published episodes and their public metadata. Use the Hosting API when your integration needs authenticated account data or API fields. This workflow applies to a custom CMS integration, including Craft CMS. Your developer must implement the connection; this is not a ready-made CMS connector.

Option 1: Read the public RSS feed

Copy the public feed URL from Standard feeds. Do not use a private subscriber feed.
Fetch and cache the feed on your server. Map each item's GUID to a stable CMS record, title to the heading, publication date to the date, and enclosure URL to the media link. Check the actual feed fields before mapping descriptions.
Refresh existing records by GUID instead of creating a duplicate on each import. Sanitize feed HTML before displaying it.

A feed can contain only a limited number of episodes. An episode missing from a later feed is not sufficient evidence that it was deleted. Do not use the feed as your only archive.

Option 2: Read episodes with the Hosting API

First, check API access as described below. Set PODIGEE_API_KEY and PODCAST_ID in your server environment. Select a public podcast that you intend to show on the website. Never expose the API key in browser JavaScript.

curl --get 'https://app.podigee.com/api/v1/episodes' \
  --header "Token: $PODIGEE_API_KEY" \
  --data-urlencode "podcast_id=$PODCAST_ID" \
  --data-urlencode 'published=true' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

The response is an array of episodes. Use id as the CMS record key. Map title, published_at, description, show_notes, cover_image, and permalink only where needed. Handle missing optional fields and sanitize HTML.
Fetch the next page with offset=50, then offset=100, and so on. Keep limit=50. Stop when a successful response contains fewer than 50 episodes.
Update records by episode ID. Cache successful results and refresh them on your server. A failed or incomplete request must not erase existing CMS records.
Define how your CMS handles unpublished or removed episodes. Reconcile only after a complete successful fetch; verify removals before deleting CMS content.

published=true filters publication state. It does not authorize you to expose private podcast content. Publish only the fields and podcasts intended for your public website. See the Hosting API reference for current request parameters and response fields.

Check API access before you build an upload workflow

The application programming interface (API) automates work in your Podigee account. An API key for your account and approval for an OAuth application are separate requirements.

Sign in to the account that will run the integration.
In the classic view, open My account > API.
Check whether the API key is available or an upgrade notice is shown.
Check that the account can access the podcast and perform the intended action.
Use the read-only podcast request below to check access before you attempt an upload.

API availability follows your account and subscription permissions. A login, access to the Applications page, or an existing podcast does not prove upload access. An organization uses its organization's subscription permissions. Older contracts can differ; do not assume a current plan comparison describes them.

If the key is missing or access is refused, send support the account and podcast links, your plan, the required workflow, and the exact error. Include expected upload volume and whether the tool serves only your account or other customers. Do not send API keys, tokens, or client secrets. Support must check eligibility; enablement is not automatic.

For an application that acts for other accounts, request OAuth application approval separately. Approval is not offered for every use case. After access is confirmed, continue with the authentication and upload instructions below.

Content requests work, but Analytics returns HTTP 403

A successful podcast or episode request confirms access to that content request. It does not confirm access to the Analytics API. Authentication identifies your account; permissions determine whether it can read the requested analytics.

Record the failing method and endpoint. For example, GET /api/v1/podcasts/{podcast_id}/analytics is an analytics request. Use the Analytics section of the API reference.
Check that the request uses the intended account's API key in the Token header, or the approved OAuth access token in Authorization: Bearer. Keep credentials on your server.
Read the response message. The Analytics API checks programmatic analytics access and permission to view analytics for the requested podcast separately.
Check the current account or organization's Analytics API entitlement and the user's podcast permissions. Viewing analytics in the website does not by itself grant external API access.

If access is still refused, send Podigee support the account and podcast identifiers, method and endpoint, HTTP status, exact sanitized error text, and request time. State whether a content request works with the same account. Remove tokens and authorization headers. Do not repeatedly regenerate keys to fix a permission error. Support must check the applicable contract and permissions; a historical plan name alone does not establish access. After access is corrected, retry the same read-only request and check the response.

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

Create (or identify) the podcast
Create an episode
Generate an upload URL
Upload the media file
Create a production for the episode using the uploaded file URL
Start the production (encoding)
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 https://app.podigee.com/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".