{"openapi":"3.1.0","info":{"title":"PodChapters API","version":"1.0.0","description":"Everything you can do in the PodChapters editor, an AI agent or your own code can do too: add episodes, transcribe them, write or generate chapters, manage presets and libraries, and export chapter files and tagged MP3s.\n\n## Authentication\n\nSend your API key as a bearer token: `Authorization: Bearer pck_…`. Create keys in [Settings → API & MCP](https://podchapters.com/app/settings/api-keys). A key acts as your account, so keep it secret and revoke it if it leaks.\n\n## MCP server\n\nEvery operation here is also a tool on the MCP server at `https://podchapters.com/api/mcp` (Streamable HTTP), with the same name, input, and output. Use the same API key, or sign in with OAuth from clients such as Claude.ai and ChatGPT. See the [setup guide](https://podchapters.com/developers).\n\n## Typical workflow\n\n1. **Add the MP3**: `create_episode` with an `audio_url`, or `create_audio_upload`, PUT the file to its `upload_url`, then `create_episode` with the `upload_key`.\n2. **Transcript**: `transcribe_episode` (1 credit per audio minute) or `upload_transcript` (free).\n3. **Chapters**: `generate_chapters` (0.04 credits per minute), or write them with `set_chapters`.\n4. **Publish**: the episode's `chapters_json_url` is the Podcasting 2.0 chapters file for `<podcast:chapters>`; `export_chapters` gives other formats and `export_mp3` embeds everything in the MP3.\n\n## Responses and errors\n\nSuccessful calls return JSON matching each operation's response schema (`201` when something was created). Failures return `{ \"error\": { \"code\", \"message\", \"hint\" } }` with the status listed for each code; `hint` says what to do next. Every response is checked against its schema before it's sent.\n\n## Plans and access\n\nYour API key can do what your PodChapters plan allows in the app. Most operations need a plan with episodes and chapters (`manual_chapters`); `transcribe_episode` and `generate_chapters` also need AI transcripts and chapters (`ai_powered_chapters_and_transcripts`). Each operation lists what it needs. Calls your plan doesn't include return `403 plan_required`, and `get_account` lists them in `access.unavailable_tools`. Admins can use everything.\n\n## Rate limits\n\n120 requests per minute per account, refilling continuously. A `429` includes `Retry-After` and `retry_after_seconds`. Paid steps are also limited by your credits; check them with `get_account` or `estimate_costs`."},"servers":[{"url":"https://podchapters.com"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"Your profile, plan, and credit balance."},{"name":"Episodes","description":"Add episodes from MP3s and edit their ID3 tags."},{"name":"Transcripts","description":"Generate, upload, and read transcripts."},{"name":"Chapters","description":"Read, write, and generate chapters, and manage chapter versions."},{"name":"Exports","description":"Chapter files in every format, and MP3s with chapters embedded."},{"name":"Snippets","description":"Reusable text that [[code]] placeholders expand to on export."},{"name":"Presets","description":"Saved ID3 tags and settings to apply to episodes."},{"name":"Chapter library","description":"Reusable chapters, such as sponsor reads."},{"name":"Image library","description":"Reusable images for artwork and chapters."},{"name":"Chapter resource pages","description":"Public pages of links that a chapter can point to."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A PodChapters API key (pck_…) from Settings → API & MCP."}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"schemas":{"Error_invalid_request":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"invalid_request"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"Error_unauthorized":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"unauthorized"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_insufficient_credits":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"insufficient_credits"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_forbidden":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"forbidden"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_plan_required":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"plan_required"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_not_found":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"not_found"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_method_not_allowed":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"method_not_allowed"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_conflict":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"conflict"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_payload_too_large":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"payload_too_large"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_rate_limited":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"rate_limited"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."},"retry_after_seconds":{"type":"integer"}}}}},"Error_internal_error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"internal_error"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_upstream_error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"upstream_error"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}},"Error_not_configured":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"not_configured"},"message":{"type":"string","description":"Written for people; safe to show as-is."},"hint":{"type":"string","description":"What to do next."}}}}}}},"paths":{"/api/v1/account":{"get":{"operationId":"get_account","summary":"Get account","description":"Returns the signed-in PodChapters account: name, email, plan, what the plan includes, and credit balance. Transcription costs 1 credit per audio minute; AI chapters cost 0.04 credits per minute. Call this first: `access.unavailable_tools` lists the tools the plan doesn't include, so you can tell the person to upgrade instead of calling them.\n\nAvailable on every plan.\n\nMCP tool: `get_account`","x-required-features":[],"tags":["Account"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"anyOf":[{"type":"object","properties":{"slug":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slug","name"],"additionalProperties":false},{"type":"null"}]},"credits":{"type":"object","properties":{"total_remaining":{"type":"number"},"monthly_remaining":{"type":"number"},"rollover_remaining":{"type":"number","description":"Unused credits carried over from earlier months"},"spent_this_month":{"type":"number"},"monthly_limit":{"type":"number"},"next_reset_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["total_remaining","monthly_remaining","rollover_remaining","spent_this_month","monthly_limit","next_reset_at"],"additionalProperties":false},"access":{"type":"object","properties":{"admin":{"type":"boolean","description":"Admins can use every tool"},"features":{"type":"array","items":{"type":"string"},"description":"Plan features, e.g. manual_chapters"},"unavailable_tools":{"type":"array","items":{"type":"string"},"description":"Tools this account's plan doesn't include"}},"required":["admin","features","unavailable_tools"],"additionalProperties":false},"auth_method":{"type":"string","enum":["api_key","oauth"]}},"required":["id","name","email","plan","credits","access","auth_method"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}}},"/api/v1/episodes":{"get":{"operationId":"list_episodes","summary":"List episodes","description":"Lists the account's episodes, newest first by default, with search, filters, and paging. Returns summaries; call get_episode for chapters, metadata, and transcript details.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `list_episodes`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"search","in":"query","required":false,"description":"Matches title, filename, podcast name, and chapter titles","schema":{"type":"string","maxLength":200}},{"name":"sort","in":"query","required":false,"schema":{"default":"updated","type":"string","enum":["updated","created","title","number","filename","podcast"]}},{"name":"order","in":"query","required":false,"schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"podcast","in":"query","required":false,"description":"Only episodes of this podcast (ID3 album)","schema":{"type":"string"}},{"name":"has_chapters","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"has_transcript","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["upload","youtube"]}},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"page_size","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"episode_number":{"anyOf":[{"type":"number"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"transcript":{"type":"string","enum":["generated","uploaded","none"],"description":"generated by PodChapters, uploaded by you, or none yet"},"source":{"type":"string","enum":["upload","youtube"]},"editor_url":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","filename","title","podcast_name","episode_number","duration_seconds","artwork_url","chapter_count","transcript","source","editor_url","created_at","updated_at"],"additionalProperties":false}},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Episodes matching the search and filters"},"podcasts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"episode_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["name","episode_count"],"additionalProperties":false},"description":"Every podcast in the account, for the podcast filter"},"note":{"type":"string"}},"required":["episodes","page","page_count","page_size","total","podcasts"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"post":{"operationId":"create_episode","summary":"Create episode","description":"Creates an episode from an MP3. Pass `audio_url` (a public URL PodChapters downloads) or `upload_key` (from create_audio_upload). PodChapters stores the audio, reads its ID3 tags, existing chapters, and artwork, applies a preset (the one you name, or the single preset whose auto-apply rule matches the filename), then applies any metadata and chapters you pass. Large files can take a minute. Next steps are usually transcribe_episode and generate_chapters.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `create_episode`","x-required-features":["manual_chapters"],"tags":["Episodes"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"audio_url":{"description":"Public URL of the MP3","type":"string","format":"uri"},"upload_key":{"description":"upload_key from create_audio_upload, after the PUT finished","type":"string"},"filename":{"description":"Episode filename, unique per account. Defaults to the URL's filename or the title.","type":"string"},"metadata":{"type":"object","properties":{"title":{"description":"Episode title (ID3 title)","type":"string"},"artist":{"description":"Author or host (ID3 artist)","type":"string"},"podcast_name":{"description":"Podcast name (ID3 album)","type":"string"},"episode_number":{"description":"Episode number (ID3 track number)","type":"integer","minimum":0,"maximum":9007199254740991},"year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"string"}]},"genre":{"description":"Defaults to \"Podcast\"","type":"string"},"description":{"description":"Episode description or short notes (ID3 comment). [[snippet]] codes expand on export.","type":"string"},"copyright":{"type":"string"},"url":{"description":"Episode or podcast URL","type":"string"},"artwork_url":{"description":"Episode artwork URL. Use upload_episode_image to host an image first.","type":"string"},"encoded_by":{"type":"string"},"transcription_keyterms":{"description":"Names and terms the transcriber should spell correctly, e.g. guest names","type":"array","items":{"type":"string"}},"transcription_replacements":{"description":"Words to replace in generated transcripts","type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}}}},"chapters":{"description":"Chapters to start with, replacing any in the file's tags","type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Chapter title, written as a heading"},"start":{"anyOf":[{"type":"number","minimum":0},{"type":"string","minLength":1}],"description":"Start time as seconds (83.5) or a timestamp (\"1:23\", \"01:23\", \"00:01:23.5\")"},"url":{"description":"Link shown with the chapter in podcast apps","type":"string"},"image_url":{"description":"Public image URL for the chapter artwork. upload_episode_image can host one for you.","type":"string"},"toc":{"description":"false hides the chapter from the table of contents (e.g. ads) while keeping its artwork and link","type":"boolean"},"location":{"type":"object","properties":{"name":{"type":"string","description":"Place name"},"geo":{"type":"string","description":"Geo URI, e.g. \"geo:30.2672,-97.7431\""},"osm":{"description":"OpenStreetMap ID, e.g. R113314","type":"string"}},"required":["name","geo"]},"utm":{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"],"description":"default uses the episode's UTM settings, custom uses the values here, disabled adds none"},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"description":"Per-chapter UTM tracking overrides for the chapter URL"}},"required":["title","start"]}},"preset_id":{"description":"Preset to apply, from list_presets","type":"string"},"apply_matching_presets":{"default":true,"description":"Apply the preset whose auto-apply rule matches the filename, when exactly one does","type":"boolean"},"import_tags":{"default":true,"description":"Read title, artwork, chapters, and other ID3 tags from the file","type":"boolean"}}},"example":{"audio_url":"https://example.com/audio/episode-42.mp3","filename":"episode-42.mp3","metadata":{"title":"Episode 42: Making better chapters","episode_number":42}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode title (ID3 title)"},"artist":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Author or host (ID3 artist)"},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Podcast name (ID3 album)"},"episode_number":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ID3 track number"},"year":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string"}]},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode description (ID3 comment)"},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode or podcast URL"},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}}},"required":["title","artist","podcast_name","episode_number","year","genre","description","copyright","url","artwork_url","encoded_by","duration_seconds","transcription_keyterms","transcription_replacements"],"additionalProperties":false},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"selected_chapter_version_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["generated","uploaded","none"],"description":"generated by PodChapters, uploaded by you, or none yet"},"hosted_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of the published transcript file"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"edited":{"type":"boolean","description":"true when edits were saved in the editor"}},"required":["status","hosted_url","filename","edited"],"additionalProperties":false},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The stored MP3, without PodChapters' tags"},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"},"youtube_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"editor_url":{"type":"string","description":"Opens the episode in the PodChapters editor"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"applied_preset":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The preset applied to the new episode, if any"}},"required":["id","filename","title","metadata","utm_settings","chapter_count","chapters","selected_chapter_version_id","transcript","audio_url","chapters_json_url","youtube_url","editor_url","created_at","updated_at","applied_preset"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"openWorld":true}}},"/api/v1/episodes/{episode_id}":{"get":{"operationId":"get_episode","summary":"Get episode","description":"Returns one episode: metadata (ID3 tags), the selected chapters, transcript status, audio URL, the hosted Podcasting 2.0 chapters JSON URL, and a link to open it in the PodChapters editor.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `get_episode`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode title (ID3 title)"},"artist":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Author or host (ID3 artist)"},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Podcast name (ID3 album)"},"episode_number":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ID3 track number"},"year":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string"}]},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode description (ID3 comment)"},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode or podcast URL"},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}}},"required":["title","artist","podcast_name","episode_number","year","genre","description","copyright","url","artwork_url","encoded_by","duration_seconds","transcription_keyterms","transcription_replacements"],"additionalProperties":false},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"selected_chapter_version_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["generated","uploaded","none"],"description":"generated by PodChapters, uploaded by you, or none yet"},"hosted_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of the published transcript file"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"edited":{"type":"boolean","description":"true when edits were saved in the editor"}},"required":["status","hosted_url","filename","edited"],"additionalProperties":false},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The stored MP3, without PodChapters' tags"},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"},"youtube_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"editor_url":{"type":"string","description":"Opens the episode in the PodChapters editor"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","filename","title","metadata","utm_settings","chapter_count","chapters","selected_chapter_version_id","transcript","audio_url","chapters_json_url","youtube_url","editor_url","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"patch":{"operationId":"update_episode","summary":"Update episode","description":"Updates an episode's metadata (ID3 tags) and UTM settings. Only the fields you pass change. The hosted chapters JSON is republished. To change chapters use set_chapters; to change the transcript use upload_transcript or transcribe_episode.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `update_episode`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"title":{"description":"Episode title (ID3 title)","type":"string"},"artist":{"description":"Author or host (ID3 artist)","type":"string"},"podcast_name":{"description":"Podcast name (ID3 album)","type":"string"},"episode_number":{"description":"Episode number (ID3 track number)","type":"integer","minimum":0,"maximum":9007199254740991},"year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"string"}]},"genre":{"description":"Defaults to \"Podcast\"","type":"string"},"description":{"description":"Episode description or short notes (ID3 comment). [[snippet]] codes expand on export.","type":"string"},"copyright":{"type":"string"},"url":{"description":"Episode or podcast URL","type":"string"},"artwork_url":{"description":"Episode artwork URL. Use upload_episode_image to host an image first.","type":"string"},"encoded_by":{"type":"string"},"transcription_keyterms":{"description":"Names and terms the transcriber should spell correctly, e.g. guest names","type":"array","items":{"type":"string"}},"transcription_replacements":{"description":"Words to replace in generated transcripts","type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}}}},"utm_settings":{"description":"UTM fields to change; omitted ones keep their saved values","type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"type":"string"},"source":{"type":"string"},"campaign_mode":{"description":"How utm_campaign is filled in","type":"string","enum":["filename","episodeNumber","custom"]},"campaign_custom":{"type":"string"}}}}},"example":{"metadata":{"title":"Episode 42: Making better chapters","transcription_keyterms":["PodChapters","Podcasting 2.0"]},"utm_settings":{"enabled":true,"source":"podcast","medium":"audio"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode title (ID3 title)"},"artist":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Author or host (ID3 artist)"},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Podcast name (ID3 album)"},"episode_number":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ID3 track number"},"year":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string"}]},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode description (ID3 comment)"},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode or podcast URL"},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}}},"required":["title","artist","podcast_name","episode_number","year","genre","description","copyright","url","artwork_url","encoded_by","duration_seconds","transcription_keyterms","transcription_replacements"],"additionalProperties":false},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"selected_chapter_version_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["generated","uploaded","none"],"description":"generated by PodChapters, uploaded by you, or none yet"},"hosted_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of the published transcript file"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"edited":{"type":"boolean","description":"true when edits were saved in the editor"}},"required":["status","hosted_url","filename","edited"],"additionalProperties":false},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The stored MP3, without PodChapters' tags"},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"},"youtube_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"editor_url":{"type":"string","description":"Opens the episode in the PodChapters editor"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","filename","title","metadata","utm_settings","chapter_count","chapters","selected_chapter_version_id","transcript","audio_url","chapters_json_url","youtube_url","editor_url","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}}},"/api/v1/uploads/audio":{"post":{"operationId":"create_audio_upload","summary":"Create audio upload URL","description":"Step 1 of adding a local MP3 file. Returns a presigned `upload_url`: send the file there with an HTTP PUT and `Content-Type: audio/mpeg` (e.g. `curl -X PUT -H 'Content-Type: audio/mpeg' --upload-file episode.mp3 \"$upload_url\"`). Then call create_episode with the returned `upload_key`. The URL expires after one hour. Skip this if the audio is already online; pass `audio_url` to create_episode instead.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `create_audio_upload`","x-required-features":["manual_chapters"],"tags":["Episodes"],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"upload_url":{"type":"string","description":"PUT the MP3 here"},"upload_key":{"type":"string","description":"Pass to create_episode once uploaded"},"method":{"type":"string","const":"PUT"},"headers":{"type":"object","properties":{"Content-Type":{"type":"string","const":"audio/mpeg"}},"required":["Content-Type"],"additionalProperties":false},"expires_at":{"type":"string"},"max_bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["upload_url","upload_key","method","headers","expires_at","max_bytes"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}}}},"/api/v1/episodes/{episode_id}/apply-preset":{"post":{"operationId":"apply_preset","summary":"Apply preset","description":"Applies a saved preset (podcast name, artist, artwork, copyright, transcription keyterms and language, UTM settings, and so on) to an episode. Only fields the preset fills in are overwritten. The preset's artwork is copied into the episode.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `apply_preset`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preset_id":{"type":"string","description":"Preset ID from list_presets"}},"required":["preset_id"]},"example":{"preset_id":"jd7f2k9w3x8m1n4p6q5r0s2t7v9y3z1a"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode title (ID3 title)"},"artist":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Author or host (ID3 artist)"},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Podcast name (ID3 album)"},"episode_number":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ID3 track number"},"year":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string"}]},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode description (ID3 comment)"},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Episode or podcast URL"},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}}},"required":["title","artist","podcast_name","episode_number","year","genre","description","copyright","url","artwork_url","encoded_by","duration_seconds","transcription_keyterms","transcription_replacements"],"additionalProperties":false},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"selected_chapter_version_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["generated","uploaded","none"],"description":"generated by PodChapters, uploaded by you, or none yet"},"hosted_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of the published transcript file"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"edited":{"type":"boolean","description":"true when edits were saved in the editor"}},"required":["status","hosted_url","filename","edited"],"additionalProperties":false},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The stored MP3, without PodChapters' tags"},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"},"youtube_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"editor_url":{"type":"string","description":"Opens the episode in the PodChapters editor"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","filename","title","metadata","utm_settings","chapter_count","chapters","selected_chapter_version_id","transcript","audio_url","chapters_json_url","youtube_url","editor_url","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}}},"/api/v1/episodes/{episode_id}/images":{"post":{"operationId":"upload_episode_image","summary":"Upload episode image","description":"Hosts an image (JPEG, PNG, WebP, or GIF up to 15 MB) in the episode's storage and returns its public URL. With kind \"artwork\" it also becomes the episode artwork. With kind \"chapter\", pass the returned URL as a chapter's image_url in set_chapters. Provide `image_url` to copy an image from the web, or `image_base64` for local files. Non-square images are padded to a square with the fill last picked in the editor (edge colors by default), and the hosted image is at most 3000 × 3000 and 1 MB. MP3 exports embed smaller copies.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `upload_episode_image`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["artwork","chapter"]},"image_url":{"type":"string","format":"uri"},"image_base64":{"description":"Base64 image bytes, optionally as a data: URL","type":"string"}},"required":["kind"]},"example":{"kind":"chapter","image_url":"https://example.com/images/guest.jpg"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public URL of the hosted image"},"kind":{"type":"string","enum":["artwork","chapter"]},"set_as_artwork":{"type":"boolean"}},"required":["url","kind","set_as_artwork"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"openWorld":true}}},"/api/v1/episodes/{episode_id}/costs":{"get":{"operationId":"estimate_costs","summary":"Estimate credit costs","description":"Returns what transcribe_episode and generate_chapters would cost for an episode, in credits, based on its length.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `estimate_costs`","x-required-features":["manual_chapters"],"tags":["Episodes"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"transcribe_episode":{"type":"number","description":"Credits transcribe_episode costs"},"generate_chapters":{"type":"number","description":"Credits generate_chapters costs"}},"required":["episode_id","duration_seconds","transcribe_episode","generate_chapters"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}}},"/api/v1/episodes/{episode_id}/transcript":{"get":{"operationId":"get_transcript","summary":"Get transcript","description":"Returns the episode's transcript, including any edits saved in the editor. Formats: text (readable paragraphs with speaker names; best for reading or summarizing), markdown (paragraphs under chapter headings, for show notes or blog posts), vtt and srt (captions), json (Podcasting 2.0 transcript), words_vtt (one cue per word with exact timings; best for finding when something was said).\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `get_transcript`","x-required-features":["manual_chapters"],"tags":["Transcripts"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}},{"name":"format","in":"query","required":false,"schema":{"default":"text","type":"string","enum":["text","markdown","vtt","srt","json","words_vtt"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"format":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string","description":"The file's contents"},"source":{"type":"string","enum":["generated","uploaded"]},"edited":{"type":"boolean","description":"true when the content includes saved edits"},"speakers":{"type":"array","items":{"type":"string"}},"hosted_url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["episode_id","format","content_type","content","source","edited","speakers","hosted_url"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"put":{"operationId":"upload_transcript","summary":"Upload transcript","description":"Publishes your own transcript for the episode, replacing any earlier transcript and its edits. Accepts WebVTT, SRT, or plain text (format is detected when omitted). Caption timings are kept; plain text is spread evenly across the episode, so generate_chapters timings will be approximate. Free.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `upload_transcript`","x-required-features":["manual_chapters"],"tags":["Transcripts"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"description":"The transcript text"},"format":{"type":"string","enum":["vtt","srt","txt"]}},"required":["content"]},"example":{"content":"WEBVTT\n\n00:00:00.000 --> 00:00:04.000\nWelcome to the show.\n","format":"vtt"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"status":{"type":"string","const":"uploaded"},"format":{"type":"string","enum":["vtt","srt","txt"]},"hosted_url":{"type":"string"},"word_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timed_by":{"type":"string","enum":["captions","estimated"],"description":"estimated for plain text, which has no timings"}},"required":["episode_id","status","format","hosted_url","word_count","timed_by"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}}}},"/api/v1/episodes/{episode_id}/transcribe":{"post":{"operationId":"transcribe_episode","summary":"Transcribe episode","description":"Transcribes the episode's audio with AI (word timings and speaker detection) and publishes it as the episode's transcript, replacing any earlier transcript and its edits. Costs 1 credit per minute of audio (1.21 for mixed languages), charged only on success. Takes about 20–60 seconds for an hour of audio. The episode's saved transcription keyterms and replacements are applied automatically. The spoken language is detected automatically unless language is set; English-only extras (filler words) apply only to English audio.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`) and AI transcripts and AI chapters (`ai_powered_chapters_and_transcripts`).\n\nMCP tool: `transcribe_episode`","x-required-features":["manual_chapters","ai_powered_chapters_and_transcripts"],"tags":["Transcripts"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"description":"Spoken language: \"auto\" to detect it (the default), \"multi\" when speakers switch languages (costs 1.21× credits), or a language code such as \"es\". Only languages enabled for PodChapters are accepted. Defaults to the episode's preset, then the language last picked in the editor, then \"auto\". Chapters are later written in the transcript's language.","type":"string"},"keyterms":{"description":"Extra names and terms to spell correctly, added to the episode's own","type":"array","items":{"type":"string"}},"replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}},"detect_speakers":{"default":true,"type":"boolean"},"include_filler_words":{"default":false,"description":"Keep \"um\", \"uh\", and similar words","type":"boolean"}}},"example":{"keyterms":["PodChapters","Daniel J. Lewis"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"status":{"type":"string","const":"generated"},"requested_language":{"type":"string","description":"What was asked for: \"auto\", \"multi\", or a language code"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language the audio was transcribed as (the most-spoken one when mixed), e.g. \"es\""},"languages":{"type":"array","items":{"type":"string"},"description":"Every language heard, most-spoken first"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"word_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credits_spent":{"type":"number"},"hosted_url":{"type":"string","description":"Public URL of the published VTT"},"preview":{"type":"string","description":"The transcript's first 600 characters"}},"required":["episode_id","status","requested_language","language","languages","duration_seconds","word_count","speaker_count","credits_spent","hosted_url","preview"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"402":{"description":"Not enough credits\n- `insufficient_credits`: The account doesn't have enough credits for this; `hint` gives the cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_insufficient_credits"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"openWorld":true}}},"/api/v1/episodes/{episode_id}/chapters":{"get":{"operationId":"get_chapters","summary":"Get chapters","description":"Returns the episode's current chapters (the selected chapter version), sorted by start time, plus the URL of the hosted Podcasting 2.0 chapters JSON that podcast hosts can reference in <podcast:chapters>.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `get_chapters`","x-required-features":["manual_chapters"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The selected chapter version"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"}},"required":["episode_id","version_id","chapter_count","chapters","chapters_json_url"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"put":{"operationId":"set_chapters","summary":"Set chapters","description":"Replaces the episode's chapters with the list you pass (send the full list, not a diff). Podcast apps need a chapter at 0:00, so an \"Introduction\" chapter is added when none starts there. By default this edits the selected chapter version, as the editor does; pass save_as \"new_version\" to keep the current version and save these as a new, selected one. Republishes the hosted chapters JSON. Free.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `set_chapters`","x-required-features":["manual_chapters"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chapters":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Chapter title, written as a heading"},"start":{"anyOf":[{"type":"number","minimum":0},{"type":"string","minLength":1}],"description":"Start time as seconds (83.5) or a timestamp (\"1:23\", \"01:23\", \"00:01:23.5\")"},"url":{"description":"Link shown with the chapter in podcast apps","type":"string"},"image_url":{"description":"Public image URL for the chapter artwork. upload_episode_image can host one for you.","type":"string"},"toc":{"description":"false hides the chapter from the table of contents (e.g. ads) while keeping its artwork and link","type":"boolean"},"location":{"type":"object","properties":{"name":{"type":"string","description":"Place name"},"geo":{"type":"string","description":"Geo URI, e.g. \"geo:30.2672,-97.7431\""},"osm":{"description":"OpenStreetMap ID, e.g. R113314","type":"string"}},"required":["name","geo"]},"utm":{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"],"description":"default uses the episode's UTM settings, custom uses the values here, disabled adds none"},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"description":"Per-chapter UTM tracking overrides for the chapter URL"}},"required":["title","start"]}},"save_as":{"default":"selected_version","type":"string","enum":["selected_version","new_version"]},"label":{"description":"Name for a new version","type":"string","maxLength":100}},"required":["chapters"]},"example":{"chapters":[{"title":"Introduction","start":0},{"title":"Why chapters matter","start":"02:15"},{"title":"Sponsor: Example Hosting","start":"14:30","url":"https://example.com","toc":false}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The selected chapter version"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"}},"required":["episode_id","version_id","chapter_count","chapters","chapters_json_url"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true,"destructive":true}}},"/api/v1/episodes/{episode_id}/chapters/generate":{"post":{"operationId":"generate_chapters","summary":"Generate chapters with AI","description":"Uses AI to write chapters from the episode's transcript and saves them as a new, selected chapter version (earlier versions are kept). mode \"suggest\" finds chapters on its own; mode \"outline\" places the chapters of an outline you provide at the right timestamps. Needs a transcript (transcribe_episode or upload_transcript first). Costs 0.04 credits per minute of audio, charged only on success. Takes 10–90 seconds.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`) and AI transcripts and AI chapters (`ai_powered_chapters_and_transcripts`).\n\nMCP tool: `generate_chapters`","x-required-features":["manual_chapters","ai_powered_chapters_and_transcripts"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"default":"suggest","type":"string","enum":["suggest","outline"]},"outline":{"description":"Required for mode outline: one section per line, in order","type":"string"},"title_style":{"description":"suggest mode: how closely titles follow the spoken words","type":"string","enum":["strict","balance","creative"]},"chapter_count":{"description":"suggest mode: how granular the chapters are","type":"string","enum":["fewer","moderate","more"]},"detect_ads":{"default":false,"description":"Mark ad and sponsor segments with an \"Ad: \" prefix, in the transcript's language (e.g. \"Anuncio: \" for Spanish)","type":"boolean"},"link_urls":{"default":false,"description":"Attach URLs mentioned in the episode to their chapters","type":"boolean"}}},"example":{"mode":"suggest","title_style":"balance","chapter_count":"moderate","detect_ads":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"version_id":{"type":"string","description":"The new, selected chapter version"},"selected":{"type":"boolean","const":true},"credits_spent":{"type":"number"},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}}},"required":["episode_id","version_id","selected","credits_spent","chapters"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"402":{"description":"Not enough credits\n- `insufficient_credits`: The account doesn't have enough credits for this; `hint` gives the cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_insufficient_credits"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"openWorld":true}}},"/api/v1/episodes/{episode_id}/chapter-versions":{"get":{"operationId":"list_chapter_versions","summary":"List chapter versions","description":"Lists the episode's chapter versions, newest first: AI generations, uploads, ID3 imports, and manual versions. One is selected; it's what get_chapters returns and what's published.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `list_chapter_versions`","x-required-features":["manual_chapters"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}},{"name":"include_chapters","in":"query","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"source":{"type":"string","enum":["outline","suggest","upload","manual","id3"],"description":"How the version was made"},"selected":{"type":"boolean"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}}},"required":["id","label","source","selected","chapter_count","created_at"],"additionalProperties":false}}},"required":["episode_id","versions"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}}},"/api/v1/episodes/{episode_id}/chapter-versions/{version_id}/select":{"post":{"operationId":"select_chapter_version","summary":"Select chapter version","description":"Makes a chapter version the episode's current chapters and republishes the hosted chapters JSON.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `select_chapter_version`","x-required-features":["manual_chapters"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1},"example":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq"},{"name":"version_id","in":"path","required":true,"description":"Chapter version ID, from list_chapter_versions","schema":{"type":"string","minLength":1},"example":"jn73chj3xt9kj461zrfp2ev3t58hb04e"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The selected chapter version"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapters":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Start time in seconds"},"start_time":{"type":"string","description":"Start time as a timestamp, e.g. \"01:35\""},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link shown with the chapter"},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter artwork"},"toc":{"type":"boolean","description":"false when the chapter is hidden from the table of contents"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]}},"required":["start","start_time","title","url","url_title","image_url","toc","location","utm"],"additionalProperties":false}},"chapters_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hosted Podcasting 2.0 chapters JSON, for <podcast:chapters>"}},"required":["episode_id","version_id","chapter_count","chapters","chapters_json_url"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}}},"/api/v1/episodes/{episode_id}/chapter-versions/{version_id}":{"delete":{"operationId":"delete_chapter_version","summary":"Delete chapter version","description":"Permanently deletes a chapter version. Deleting the selected version leaves the episode without selected chapters until you select another.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `delete_chapter_version`","x-required-features":["manual_chapters"],"tags":["Chapters"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}},{"name":"version_id","in":"path","required":true,"description":"Chapter version ID, from list_chapter_versions","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"version_id":{"type":"string"}},"required":["deleted","version_id"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true,"idempotent":true}}},"/api/v1/episodes/{episode_id}/chapters/export":{"get":{"operationId":"export_chapters","summary":"Export chapters","description":"Exports the episode's chapters with snippets expanded and UTM tags applied. Formats: podcasting2_json (the <podcast:chapters> JSON file), podlove_xml (Podlove Simple Chapters), youtube (timestamps for a YouTube description), text_outline (\"Title [00:00]\" lines), markdown_outline (headings with links, for show notes).\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `export_chapters`","x-required-features":["manual_chapters"],"tags":["Exports"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}},{"name":"format","in":"query","required":false,"schema":{"default":"podcasting2_json","type":"string","enum":["podcasting2_json","podlove_xml","youtube","text_outline","markdown_outline"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"format":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string","description":"The file's contents"},"hosted_url":{"description":"For podcasting2_json: the episode's hosted copy","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["episode_id","format","content_type","content"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}}},"/api/v1/episodes/{episode_id}/export-mp3":{"post":{"operationId":"export_mp3","summary":"Export MP3 with chapters","description":"Builds a copy of the episode's MP3 with its chapters, chapter images and links, and metadata (title, artwork, description, and more) embedded as ID3 tags, and returns a download URL. Re-run after changing chapters or metadata. Takes a few seconds per 100 MB.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `export_mp3`","x-required-features":["manual_chapters"],"tags":["Exports"],"parameters":[{"name":"episode_id","in":"path","required":true,"description":"Episode ID, from list_episodes or create_episode","schema":{"type":"string","minLength":1}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string"},"download_url":{"type":"string","description":"Public URL of the tagged MP3"},"filename":{"type":"string"},"size_bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["episode_id","download_url","filename","size_bytes","chapter_count"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}}},"/api/v1/snippets":{"get":{"operationId":"list_snippets","summary":"List snippets","description":"Lists the account's snippets. A snippet is reusable text: writing [[code]] in a chapter title, URL, or episode description inserts the snippet's value when chapters and metadata are exported (hosted chapters JSON, MP3 tags, outlines).\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `list_snippets`","x-required-features":["manual_chapters"],"tags":["Snippets"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"snippets":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"placeholder":{"type":"string","description":"Write this to insert the snippet"},"value":{"type":"string"}},"required":["code","placeholder","value"],"additionalProperties":false}}},"required":["snippets"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}}},"/api/v1/snippets/{code}":{"put":{"operationId":"set_snippet","summary":"Set snippet","description":"Creates a snippet, or replaces the value of an existing one with the same code. Use [[code]] anywhere in chapters or episode metadata to insert the value on export.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `set_snippet`","x-required-features":["manual_chapters"],"tags":["Snippets"],"parameters":[{"name":"code","in":"path","required":true,"description":"Snippet code, with or without brackets: \"sponsor\" or \"[[sponsor]]\". Stored lowercase with spaces as underscores.","schema":{"type":"string","minLength":1},"example":"sponsor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"Text inserted wherever [[code]] appears"}},"required":["value"]},"example":{"value":"Thanks to Acme for supporting the show"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"placeholder":{"type":"string","description":"Write this to insert the snippet"},"value":{"type":"string"}},"required":["code","placeholder","value"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}},"delete":{"operationId":"delete_snippet","summary":"Delete snippet","description":"Deletes a snippet. Chapters and metadata that still contain its [[code]] keep the placeholder text unexpanded.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `delete_snippet`","x-required-features":["manual_chapters"],"tags":["Snippets"],"parameters":[{"name":"code","in":"path","required":true,"description":"Snippet code, with or without brackets: \"sponsor\" or \"[[sponsor]]\". Stored lowercase with spaces as underscores.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"code":{"type":"string"}},"required":["deleted","code"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true,"idempotent":true}}},"/api/v1/presets":{"get":{"operationId":"list_presets","summary":"List presets","description":"Lists the account's presets. A preset holds metadata shared by a show's episodes (podcast name, artist, artwork, copyright, transcription keyterms and language, UTM settings). Apply one to an episode with apply_preset, or name it in create_episode. A preset with auto_apply is applied automatically to new episodes whose filename matches.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `list_presets`","x-required-features":["manual_chapters"],"tags":["Presets"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"presets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"artist":{"anyOf":[{"type":"string"},{"type":"null"}]},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"episode_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"year":{"anyOf":[{"type":"string"},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}},"speaker_names":{"type":"array","items":{"type":"string"}},"transcription_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Spoken language used when transcribing: \"auto\", \"multi\", or a code such as \"es\""},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"auto_apply":{"anyOf":[{"type":"object","properties":{"pattern":{"type":"string"},"match_type":{"type":"string","enum":["startsWith","endsWith","contains"]}},"required":["pattern","match_type"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","title","artist","podcast_name","episode_number","year","genre","description","copyright","url","encoded_by","artwork_url","transcription_keyterms","transcription_replacements","speaker_names","transcription_language","utm_settings","auto_apply"],"additionalProperties":false}}},"required":["presets"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"post":{"operationId":"create_preset","summary":"Create preset","description":"Creates a preset of metadata to reuse across a show's episodes. Only the fields you fill in are applied to episodes; empty fields leave the episode's value alone. Names must be unique.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `create_preset`","x-required-features":["manual_chapters"],"tags":["Presets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Episode title (ID3 title)","type":"string"},"artist":{"description":"Author or host (ID3 artist)","type":"string"},"podcast_name":{"description":"Podcast name (ID3 album)","type":"string"},"episode_number":{"description":"Episode number (ID3 track number)","anyOf":[{"type":"string"},{"type":"number"}]},"year":{"anyOf":[{"type":"string"},{"type":"number"}]},"genre":{"type":"string"},"description":{"description":"Episode description (ID3 comment). [[snippet]] codes work.","type":"string"},"copyright":{"type":"string"},"url":{"description":"Episode or podcast URL","type":"string"},"encoded_by":{"type":"string"},"transcription_keyterms":{"description":"Names and terms the transcriber should spell correctly","type":"array","items":{"type":"string"}},"transcription_replacements":{"description":"Words to replace in generated transcripts","type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}},"speaker_names":{"description":"Names offered when renaming speakers in the transcript editor","type":"array","items":{"type":"string"}},"transcription_language":{"description":"Spoken language of this show's episodes, used when transcribing: \"auto\", \"multi\" (mixed languages, 1.21× credits), or a language code such as \"es\". A language that isn't enabled for PodChapters falls back to auto-detect. null clears it, so the account's last-picked choice applies.","anyOf":[{"type":"string"},{"type":"null"}]},"utm_settings":{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"type":"string"},"source":{"type":"string"},"campaign_mode":{"description":"How utm_campaign is filled in","type":"string","enum":["filename","episodeNumber","custom"]},"campaign_custom":{"type":"string"}},"required":["enabled"],"description":"UTM tracking parameters added to chapter URLs on export"},"name":{"type":"string","minLength":1,"description":"Preset name, unique per account"},"auto_apply":{"type":"object","properties":{"pattern":{"type":"string","minLength":1},"match_type":{"type":"string","enum":["startsWith","endsWith","contains"]}},"required":["pattern","match_type"],"description":"Apply this preset automatically to new episodes whose filename matches (case-insensitive)"},"artwork_url":{"description":"Image URL to download as the preset artwork (JPEG, PNG, WebP, or GIF, up to 15 MB). Pass \"\" to remove the artwork.","type":"string"},"artwork_base64":{"description":"Base64 image bytes for the artwork, optionally as a data: URL","type":"string"}},"required":["name"]},"example":{"name":"The Weekly Show","podcast_name":"The Weekly Show","artist":"Ada Lovelace","copyright":"© 2026 Weekly Media","genre":"Podcast","transcription_keyterms":["PodChapters","Lovelace"],"auto_apply":{"pattern":"weekly-","match_type":"startsWith"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"artist":{"anyOf":[{"type":"string"},{"type":"null"}]},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"episode_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"year":{"anyOf":[{"type":"string"},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}},"speaker_names":{"type":"array","items":{"type":"string"}},"transcription_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Spoken language used when transcribing: \"auto\", \"multi\", or a code such as \"es\""},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"auto_apply":{"anyOf":[{"type":"object","properties":{"pattern":{"type":"string"},"match_type":{"type":"string","enum":["startsWith","endsWith","contains"]}},"required":["pattern","match_type"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","title","artist","podcast_name","episode_number","year","genre","description","copyright","url","encoded_by","artwork_url","transcription_keyterms","transcription_replacements","speaker_names","transcription_language","utm_settings","auto_apply"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}}}},"/api/v1/presets/{preset_id}":{"patch":{"operationId":"update_preset","summary":"Update preset","description":"Changes a preset. Only the fields you pass change; pass \"\" to clear a text field. Episodes that already used the preset keep their values.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `update_preset`","x-required-features":["manual_chapters"],"tags":["Presets"],"parameters":[{"name":"preset_id","in":"path","required":true,"description":"Preset ID from list_presets","schema":{"type":"string"},"example":"jd7f3k2m9x8q4w6e1r5t0y2u3i4o5p6a"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Episode title (ID3 title)","type":"string"},"artist":{"description":"Author or host (ID3 artist)","type":"string"},"podcast_name":{"description":"Podcast name (ID3 album)","type":"string"},"episode_number":{"description":"Episode number (ID3 track number)","anyOf":[{"type":"string"},{"type":"number"}]},"year":{"anyOf":[{"type":"string"},{"type":"number"}]},"genre":{"type":"string"},"description":{"description":"Episode description (ID3 comment). [[snippet]] codes work.","type":"string"},"copyright":{"type":"string"},"url":{"description":"Episode or podcast URL","type":"string"},"encoded_by":{"type":"string"},"transcription_keyterms":{"description":"Names and terms the transcriber should spell correctly","type":"array","items":{"type":"string"}},"transcription_replacements":{"description":"Words to replace in generated transcripts","type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}},"speaker_names":{"description":"Names offered when renaming speakers in the transcript editor","type":"array","items":{"type":"string"}},"transcription_language":{"description":"Spoken language of this show's episodes, used when transcribing: \"auto\", \"multi\" (mixed languages, 1.21× credits), or a language code such as \"es\". A language that isn't enabled for PodChapters falls back to auto-detect. null clears it, so the account's last-picked choice applies.","anyOf":[{"type":"string"},{"type":"null"}]},"utm_settings":{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"type":"string"},"source":{"type":"string"},"campaign_mode":{"description":"How utm_campaign is filled in","type":"string","enum":["filename","episodeNumber","custom"]},"campaign_custom":{"type":"string"}},"required":["enabled"],"description":"UTM tracking parameters added to chapter URLs on export"},"name":{"type":"string","minLength":1},"auto_apply":{"description":"Pass null to stop applying the preset automatically","anyOf":[{"type":"object","properties":{"pattern":{"type":"string","minLength":1},"match_type":{"type":"string","enum":["startsWith","endsWith","contains"]}},"required":["pattern","match_type"],"description":"Apply this preset automatically to new episodes whose filename matches (case-insensitive)"},{"type":"null"}]},"artwork_url":{"description":"Image URL to download as the preset artwork (JPEG, PNG, WebP, or GIF, up to 15 MB). Pass \"\" to remove the artwork.","type":"string"},"artwork_base64":{"description":"Base64 image bytes for the artwork, optionally as a data: URL","type":"string"}}},"example":{"copyright":"© 2027 Weekly Media","auto_apply":null}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"artist":{"anyOf":[{"type":"string"},{"type":"null"}]},"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"episode_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"year":{"anyOf":[{"type":"string"},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"copyright":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"encoded_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"artwork_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcription_keyterms":{"type":"array","items":{"type":"string"}},"transcription_replacements":{"type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"],"additionalProperties":false}},"speaker_names":{"type":"array","items":{"type":"string"}},"transcription_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Spoken language used when transcribing: \"auto\", \"multi\", or a code such as \"es\""},"utm_settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"medium":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_mode":{"anyOf":[{"type":"string","enum":["filename","episodeNumber","custom"]},{"type":"null"}]},"campaign_custom":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","medium","source","campaign_mode","campaign_custom"],"additionalProperties":false},{"type":"null"}],"description":"UTM tracking added to chapter URLs on export"},"auto_apply":{"anyOf":[{"type":"object","properties":{"pattern":{"type":"string"},"match_type":{"type":"string","enum":["startsWith","endsWith","contains"]}},"required":["pattern","match_type"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","title","artist","podcast_name","episode_number","year","genre","description","copyright","url","encoded_by","artwork_url","transcription_keyterms","transcription_replacements","speaker_names","transcription_language","utm_settings","auto_apply"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"idempotent":true}},"delete":{"operationId":"delete_preset","summary":"Delete preset","description":"Deletes a preset. Episodes that used it keep their metadata and artwork.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `delete_preset`","x-required-features":["manual_chapters"],"tags":["Presets"],"parameters":[{"name":"preset_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true,"idempotent":true}}},"/api/v1/chapter-library":{"get":{"operationId":"list_library_chapters","summary":"List library chapters","description":"Lists chapters saved to the chapter library, newest first. Library chapters are reusable chapters (e.g. a recurring sponsor or segment) with a title, link, artwork, and location but no start time. To use one in an episode, copy its fields into set_chapters with a start time.\n\nAvailable on every plan.\n\nMCP tool: `list_library_chapters`","x-required-features":[],"tags":["Chapter library"],"parameters":[{"name":"search","in":"query","required":false,"description":"Matches the library name or chapter title","schema":{"type":"string"}},{"name":"tags","in":"query","required":false,"description":"Only chapters with all of these tags","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page; omit for the first page","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"chapters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"image_library_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The image library image used as artwork, if any"},"toc":{"type":"boolean"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","title","url","url_title","image_url","image_library_id","toc","location","utm","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` for the next page; null on the last page"}},"required":["chapters","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"post":{"operationId":"create_library_chapter","summary":"Save chapter to library","description":"Saves a reusable chapter to the chapter library. If an identical chapter is already saved, returns that one with is_duplicate true instead of saving a copy.\n\nAvailable on every plan.\n\nMCP tool: `create_library_chapter`","x-required-features":[],"tags":["Chapter library"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Chapter title"},"url":{"type":"string"},"image_url":{"description":"Public image URL for the chapter artwork","type":"string"},"image_library_id":{"description":"Use an image from the image library (list_library_images) as the artwork","type":"string"},"toc":{"description":"false hides the chapter from the table of contents","type":"boolean"},"location":{"type":"object","properties":{"name":{"type":"string","description":"Place name"},"geo":{"type":"string","description":"Geo URI, e.g. \"geo:30.2672,-97.7431\""},"osm":{"description":"OpenStreetMap ID, e.g. R113314","type":"string"}},"required":["name","geo"]},"utm":{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"],"description":"default uses the episode's UTM settings, custom uses the values here, disabled adds none"},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"description":"Per-chapter UTM tracking overrides for the chapter URL"},"name":{"description":"Name in the library; defaults to the title","type":"string","minLength":1,"maxLength":120},"tags":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"description":"Up to 20 tags, stored lowercase"}},"required":["title"]},"example":{"name":"Acme sponsor read","title":"Ad: Acme","url":"https://acme.example.com/podcast","toc":false,"tags":["sponsor"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"chapter":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"image_library_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The image library image used as artwork, if any"},"toc":{"type":"boolean"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","title","url","url_title","image_url","image_library_id","toc","location","utm","created_at","updated_at"],"additionalProperties":false},"is_duplicate":{"type":"boolean","description":"true when an identical chapter was already saved"}},"required":["chapter","is_duplicate"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}}}},"/api/v1/chapter-library/{chapter_id}":{"patch":{"operationId":"update_library_chapter","summary":"Update library chapter","description":"Changes a library chapter. Only the fields you pass change. Episodes that already used the chapter aren't affected.\n\nAvailable on every plan.\n\nMCP tool: `update_library_chapter`","x-required-features":[],"tags":["Chapter library"],"parameters":[{"name":"chapter_id","in":"path","required":true,"description":"Library chapter ID from list_library_chapters","schema":{"type":"string"},"example":"kh72n9d4x1c8v5b3m6q0w2e7r4t9y1u3"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Chapter title"},"url":{"type":"string"},"image_url":{"description":"Public image URL for the chapter artwork","type":"string"},"image_library_id":{"description":"Use an image from the image library (list_library_images) as the artwork","type":"string"},"toc":{"description":"false hides the chapter from the table of contents","type":"boolean"},"location":{"type":"object","properties":{"name":{"type":"string","description":"Place name"},"geo":{"type":"string","description":"Geo URI, e.g. \"geo:30.2672,-97.7431\""},"osm":{"description":"OpenStreetMap ID, e.g. R113314","type":"string"}},"required":["name","geo"]},"utm":{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"],"description":"default uses the episode's UTM settings, custom uses the values here, disabled adds none"},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"description":"Per-chapter UTM tracking overrides for the chapter URL"},"name":{"type":"string","minLength":1,"maxLength":120},"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"description":"Up to 20 tags, stored lowercase"}}},"example":{"url":"https://acme.example.com/podcast?offer=spring"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"title":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"url_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the linked page, when it was looked up"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"image_library_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The image library image used as artwork, if any"},"toc":{"type":"boolean"},"location":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"geo":{"type":"string"},"osm":{"type":"string"}},"required":["name","geo"],"additionalProperties":false},{"type":"null"}]},"utm":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["default","custom","disabled"]},"medium":{"type":"string"},"source":{"type":"string"},"campaign":{"type":"string"},"content":{"type":"string"}},"required":["mode"],"additionalProperties":false},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","title","url","url_title","image_url","image_library_id","toc","location","utm","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}},"delete":{"operationId":"delete_library_chapter","summary":"Delete library chapter","description":"Removes a chapter from the chapter library; it's permanently deleted a few seconds later. Episodes that already used it keep their chapters.\n\nAvailable on every plan.\n\nMCP tool: `delete_library_chapter`","x-required-features":[],"tags":["Chapter library"],"parameters":[{"name":"chapter_id","in":"path","required":true,"description":"Library chapter ID from list_library_chapters","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true}}},"/api/v1/image-library":{"get":{"operationId":"list_library_images","summary":"List library images","description":"Lists images in the image library, most recently updated first. Use an image's `url` as an episode's artwork_url or a chapter's image_url (the episode gets its own copy, so deleting the library image later doesn't affect it), or its `id` as image_library_id for library chapters.\n\nAvailable on every plan.\n\nMCP tool: `list_library_images`","x-required-features":[],"tags":["Image library"],"parameters":[{"name":"search","in":"query","required":false,"description":"Matches the image name","schema":{"type":"string"}},{"name":"tags","in":"query","required":false,"description":"Only images with all of these tags","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page; omit for the first page","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"url":{"type":"string","description":"Public URL of the image"},"content_type":{"type":"string"},"byte_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","url","content_type","byte_size","width","height","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` for the next page; null on the last page"}},"required":["images","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"post":{"operationId":"add_library_image","summary":"Add library image","description":"Adds an image (JPEG, PNG, WebP, or GIF up to 15 MB) to the image library from `image_url` or `image_base64`. If the same image is already in the library, returns it with is_duplicate true.\n\nAvailable on every plan.\n\nMCP tool: `add_library_image`","x-required-features":[],"tags":["Image library"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","format":"uri"},"image_base64":{"description":"Base64 image bytes, optionally as a data: URL","type":"string"},"name":{"description":"Defaults to the URL's filename or \"Untitled image\"","type":"string","minLength":1,"maxLength":120},"tags":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"description":"Up to 20 tags, stored lowercase"}}},"example":{"image_url":"https://example.com/images/acme-logo.png","name":"Acme logo","tags":["sponsor"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"url":{"type":"string","description":"Public URL of the image"},"content_type":{"type":"string"},"byte_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","url","content_type","byte_size","width","height","created_at","updated_at"],"additionalProperties":false},"is_duplicate":{"type":"boolean","description":"true when the same image was already in the library"}},"required":["image","is_duplicate"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"413":{"description":"Too large\n- `payload_too_large`: A file or text is over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_payload_too_large"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}},"502":{"description":"Upstream service failed\n- `upstream_error`: A service PodChapters relies on (AI, transcription, or a URL you gave) failed. No credits were spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_upstream_error"}}}}},"x-annotations":{"openWorld":true}}},"/api/v1/image-library/{image_id}":{"patch":{"operationId":"update_library_image","summary":"Update library image","description":"Renames a library image or changes its tags.\n\nAvailable on every plan.\n\nMCP tool: `update_library_image`","x-required-features":[],"tags":["Image library"],"parameters":[{"name":"image_id","in":"path","required":true,"description":"Library image ID from list_library_images","schema":{"type":"string"},"example":"md81c4v7b2n5m9x3z6q0w4e8r1t5y2u7"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"description":"Up to 20 tags, stored lowercase"}}},"example":{"name":"Acme logo (square)","tags":["sponsor","logo"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"url":{"type":"string","description":"Public URL of the image"},"content_type":{"type":"string"},"byte_size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","name","tags","url","content_type","byte_size","width","height","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}},"delete":{"operationId":"delete_library_image","summary":"Delete library image","description":"Permanently deletes an image from the image library. Episodes and chapters that copied the image keep their copies. Fails while a saved library chapter uses the image; delete or change that chapter first.\n\nAvailable on every plan.\n\nMCP tool: `delete_library_image`","x-required-features":[],"tags":["Image library"],"parameters":[{"name":"image_id","in":"path","required":true,"description":"Library image ID from list_library_images","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"409":{"description":"Conflict\n- `conflict`: The request clashes with the current state, e.g. a name is taken or a transcript is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_conflict"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true}}},"/api/v1/resource-pages":{"get":{"operationId":"list_resource_pages","summary":"List chapter resource pages","description":"Lists the account's chapter resource pages, most recently updated first. A chapter resource page is a simple public page of links, text, and images for one chapter; point a chapter's url at the page's `url` to link it. Requires the Smart plan or higher to publish.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `list_resource_pages`","x-required-features":["manual_chapters"],"tags":["Chapter resource pages"],"parameters":[{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page; omit for the first page","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"resource_pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Public page URL; link a chapter to it"},"episode_id":{"type":"string"},"episode_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the page's episode, when the listing includes it"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"],"additionalProperties":false}]}},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","slug","title","url","episode_id","episode_title","blocks","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` for the next page; null on the last page"}},"required":["resource_pages","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"post":{"operationId":"create_resource_page","summary":"Create chapter resource page","description":"Creates a public chapter resource page for an episode and returns its `url`. Then link it from a chapter by setting that chapter's url to the page URL with set_chapters. Up to 50 sections. Requires the Smart plan or higher.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `create_resource_page`","x-required-features":["manual_chapters"],"tags":["Chapter resource pages"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string","minLength":1,"description":"Episode ID, from list_episodes or create_episode"},"title":{"type":"string","minLength":1,"maxLength":200},"blocks":{"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"]},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"]},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"]}]},"description":"Page sections, top to bottom"}},"required":["episode_id","title","blocks"]},"example":{"episode_id":"k57e4zbqnw4t6zqknq0zeckemd8hb5vq","title":"Links from episode 12","blocks":[{"kind":"text","html":"<p>Everything we mentioned in this segment.</p>"},{"kind":"button","label":"Get the book","url":"https://example.com/book"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Public page URL; link a chapter to it"},"episode_id":{"type":"string"},"episode_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the page's episode, when the listing includes it"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"],"additionalProperties":false}]}},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","slug","title","url","episode_id","episode_title","blocks","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `forbidden`: The account can't do this, e.g. its plan doesn't include it.\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error_forbidden"},{"$ref":"#/components/schemas/Error_plan_required"}]}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}}}},"/api/v1/resource-pages/{slug}":{"get":{"operationId":"get_resource_page","summary":"Get chapter resource page","description":"Returns one of the account's chapter resource pages by slug.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `get_resource_page`","x-required-features":["manual_chapters"],"tags":["Chapter resource pages"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Chapter resource page slug, from list_resource_pages or create_resource_page","schema":{"type":"string","pattern":"^[a-z0-9]{6,32}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Public page URL; link a chapter to it"},"episode_id":{"type":"string"},"episode_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the page's episode, when the listing includes it"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"],"additionalProperties":false}]}},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","slug","title","url","episode_id","episode_title","blocks","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"readOnly":true,"idempotent":true}},"patch":{"operationId":"update_resource_page","summary":"Update chapter resource page","description":"Changes a chapter resource page's title or sections. Passing `blocks` replaces all sections. The page URL stays the same.\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `update_resource_page`","x-required-features":["manual_chapters"],"tags":["Chapter resource pages"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Chapter resource page slug, from list_resource_pages or create_resource_page","schema":{"type":"string","pattern":"^[a-z0-9]{6,32}$"},"example":"a1b2c3d4e5"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"blocks":{"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"]},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"]},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"]}]},"description":"Page sections, top to bottom"}}},"example":{"title":"Links from episode 12 (updated)"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Public page URL; link a chapter to it"},"episode_id":{"type":"string"},"episode_title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the page's episode, when the listing includes it"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"text"},"html":{"type":"string","maxLength":20000,"description":"Rich text as HTML (paragraphs, headings, lists, bold, italic, links). Unsupported tags are removed."}},"required":["kind","html"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"button"},"label":{"type":"string","maxLength":120},"url":{"type":"string","description":"Link the button opens"}},"required":["kind","label","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"image"},"url":{"type":"string","description":"Public http(s) image URL"},"alt":{"description":"Image description for screen readers","type":"string","maxLength":300}},"required":["kind","url"],"additionalProperties":false}]}},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time, e.g. 2026-11-14T15:04:05.000Z"}},"required":["id","slug","title","url","episode_id","episode_title","blocks","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `forbidden`: The account can't do this, e.g. its plan doesn't include it.\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error_forbidden"},{"$ref":"#/components/schemas/Error_plan_required"}]}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"idempotent":true}},"delete":{"operationId":"delete_resource_page","summary":"Delete chapter resource page","description":"Deletes a chapter resource page. Its URL stops working, so remove or change any chapter links to it (set_chapters).\n\nPlan needs: Episodes, chapters, presets, and snippets (`manual_chapters`).\n\nMCP tool: `delete_resource_page`","x-required-features":["manual_chapters"],"tags":["Chapter resource pages"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Chapter resource page slug, from list_resource_pages or create_resource_page","schema":{"type":"string","pattern":"^[a-z0-9]{6,32}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"slug":{"type":"string"}},"required":["deleted","slug"],"additionalProperties":false}}}},"400":{"description":"Invalid input\n- `invalid_request`: The input doesn't match the schema; `details` lists each problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_invalid_request"}}}},"401":{"description":"Missing or invalid API key\n- `unauthorized`: Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_unauthorized"}}}},"403":{"description":"Not allowed\n- `plan_required`: The account's plan doesn't include this; `details.required_features` lists what's missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_plan_required"}}}},"404":{"description":"Not found\n- `not_found`: The episode or item doesn't exist or isn't yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_not_found"}}}},"429":{"description":"Rate limited\n- `rate_limited`: Too many requests; retry after `retry_after_seconds`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_rate_limited"}}}},"500":{"description":"Server error\n- `internal_error`: Something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error_internal_error"}}}}},"x-annotations":{"destructive":true,"idempotent":true}}}}}