PodChapters API & MCP server

Everything you do in the PodChapters editor, an AI agent or your own code can do too: add episodes, transcribe them, generate and edit chapters, manage presets and libraries, and export chapters in every format PodChapters supports.

The same 40 operations are available two ways: as tools on an MCP server for agents like Claude, ChatGPT, and Cursor, and as a REST API with an OpenAPI spec. The interactive API reference documents every input, response, and error, and lets you try each call.

Authentication

Create an API key in Settings → API & MCP and send it as a bearer token: Authorization: Bearer pck_…. A key acts as your account, so keep it secret and revoke it if it leaks.

MCP clients that support OAuth, such as Claude.ai and ChatGPT custom connectors, need no key: add the MCP server URL and sign in to PodChapters when asked.

A key can do what your plan allows in the app. Most tools need a plan with episodes and chapters, and AI transcripts and chapters need a plan that includes them. get_account lists anything your plan doesn't include, and those calls return 403 plan_required.

Connect an AI agent

The MCP server uses the Streamable HTTP transport at https://podchapters.com/api/mcp.

Claude Code

claude mcp add --transport http podchapters https://podchapters.com/api/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Cursor and other MCP clients

{
  "mcpServers": {
    "podchapters": {
      "url": "https://podchapters.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Claude.ai and ChatGPT

Add a custom connector with the URL https://podchapters.com/api/mcp and sign in with your PodChapters account.

REST quickstart

Every tool is also an endpoint under /api/v1. Requests and responses are JSON with snake_case fields.

curl -H "Authorization: Bearer YOUR_KEY" https://podchapters.com/api/v1/account

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/episode-42.mp3"}' \
  https://podchapters.com/api/v1/episodes

Typical workflow

  1. create_audio_upload: For a local MP3, get a presigned upload_url and PUT the file to it. Skip this when the audio is already online.
  2. create_episode: Pass the upload_key, or an audio_url. PodChapters reads the file’s ID3 tags, artwork, and chapters and applies a matching preset.
  3. transcribe_episode: Makes a transcript with speaker detection. Or provide your own with upload_transcript.
  4. generate_chapters: Let AI suggest chapters, or pass your outline and let AI place each point at the right time. Adjust them with set_chapters.
  5. export_chapters: Get Podcasting 2.0 JSON, Podlove XML, YouTube timestamps, or an outline; or use export_mp3 for an MP3 with the chapters and tags embedded. Every episode also has a hosted chapters_json_url for your feed’s <podcast:chapters> tag, kept up to date as chapters change.

Credits

The API uses the same credits as the editor. Transcription costs 1 credit per minute of audio; AI chapters cost 0.04 credits per minute. PodChapters checks your balance first and charges only after the work succeeds. Check your balance with get_account.

Errors and rate limits

Errors use standard HTTP status codes and a JSON body. The hint says what to do next.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits",
    "hint": "Transcribing this episode costs 42 credits (1 per minute). Check get_account for the balance."
  }
}

Each account can make 120 requests per minute. Beyond that, requests get a 429 response with retry_after_seconds.

Reference

The interactive API reference has every operation's inputs, response, and possible errors, with examples you can run. Each operation is also an MCP tool with the same name:

Account
get_account
Episodes
list_episodesget_episodecreate_audio_uploadcreate_episodeupdate_episodeapply_presetupload_episode_imageestimate_costs
Transcripts
get_transcripttranscribe_episodeupload_transcript
Chapters
get_chaptersset_chaptersgenerate_chapterslist_chapter_versionsselect_chapter_versiondelete_chapter_version
Exports
export_chaptersexport_mp3
Snippets
list_snippetsset_snippetdelete_snippet
Presets
list_presetscreate_presetupdate_presetdelete_preset
Chapter library
list_library_chapterscreate_library_chapterupdate_library_chapterdelete_library_chapter
Image library
list_library_imagesadd_library_imageupdate_library_imagedelete_library_image
Chapter resource pages
list_resource_pagesget_resource_pagecreate_resource_pageupdate_resource_pagedelete_resource_page