PodBox API reference
Every PodBox method is both an MCP tool and a REST endpoint, with the same arguments and the same OAuth token. Connect with the MCP server or call the REST API. The OpenAPI document describes the same endpoints.
Episodes
Publish a narrated script or an uploaded audio file as an episode, then read, update, or delete it.
Publish narration
Creates an episode by narrating a script with text-to-speech.
PodBox renders the script in the background and adds the episode to the feed when rendering finishes. To follow its progress, call read_episode with the returned episodeId.
Each part of the script is either speech in one of two English voices or a silence. PodBox reads the text literally, so write it for listening. If rendering doesn't finish within 1 hour, the episode's status becomes failed.
Narration uses credits. While the episode renders, account_status counts them as reserved. If the account doesn't have enough credits, the call fails with insufficientCredits, and the error includes a link. Over MCP the link is the PodBox support page. Over HTTP it is the dashboard subscription page. If the account can't store another episode, the call fails with storageClosed or episodeLimit, and the error includes a link. Over MCP the link is the PodBox support page. Over HTTP it is the dashboard subscription page.
The idempotencyKey makes the call safe to retry. A call with a key you already used returns the same episode, even after it has published, and never creates a second episode or charges again. When the response has a status of replay, call read_episode instead of sending the script again.
Request
- MCP
tools/call create_speech_episode- HTTP
POST https://api.podbox.sh/api/v1/episodes/speech
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
title | string | Yes | body | The episode title in the feed, from 1 through 256 characters. |
description | string | Yes | body | The episode description, up to 4,096 characters. To leave it blank, send an empty string. |
idempotencyKey | string | Yes | body | A key you choose for this episode, from 1 through 200 characters with no whitespace. Send the same key when you retry the same request. |
script | array | Yes | body | The parts of the script, in the order they play. From 1 through 8 parts. Each item is one of these objects:
|
Response
The new episode's episodeId, with a status of held. A retry with a used idempotencyKey returns a status of replay, and can include episode, the episode's current status.
Start upload
Creates an upload hold for an audio file and returns the URLs to upload it to.
Publishing an audio file takes three steps. Call this method with the file's type and size. Split the file into parts in partNumber order, each one length bytes long, and upload each part to its url with an HTTP PUT request. Then call complete_episode to publish the episode.
Complete the upload within 24 hours. After that, PodBox voids the hold and the part URLs stop working.
If the account can't store another episode, the call fails with storageClosed or episodeLimit, and the error includes a link. Over MCP the link is the PodBox support page. Over HTTP it is the dashboard subscription page.
The idempotencyKey makes the call safe to retry. A retry with the same key returns the same episode, even after it has published, and never creates a second episode or charges again. A response with parts is a hold that is still open, so upload to it. A response with a status of replay and no parts means the episode already exists. Don't upload it again. Call read_episode to check its status.
Request
- MCP
tools/call hold_episode- HTTP
POST https://api.podbox.sh/api/v1/episodes
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
title | string | Yes | body | The episode title in the feed, from 1 through 256 characters. |
description | string | Yes | body | The episode description, up to 4,096 characters. To leave it blank, send an empty string. |
contentType | string | Yes | body | The audio format of the file. The uploaded bytes must be this format, or complete_episode rejects them. One of audio/mpeg, audio/mp4, audio/aac, audio/wav, audio/x-m4a. |
bytes | integer | Yes | body | The exact size of the file in bytes, up to 1 GiB. |
idempotencyKey | string | Yes | body | A key you choose for this episode, from 1 through 200 characters with no whitespace. Send the same key when you retry the same request. |
durationSeconds | integer | No | body | The length of the audio in whole seconds, from 1 through 864,000. |
Response
The new episode's episodeId, with a status of held and the parts to upload. Each part has a partNumber, a url, and a length in bytes. A retry returns a status of replay, can leave out parts, and can include episode, the episode's current status.
Publish upload
Publishes an uploaded audio file as an episode.
Call this method after you upload every part that hold_episode returned. PodBox checks that the stored bytes are the audio format the hold declared, charges credits for the upload, and adds the episode to the feed.
If the bytes aren't that format, the call fails with badAudio. Nothing is charged and the hold stays open, so you can upload the file again and call this method again. If a part isn't uploaded yet, the call fails with objectMissing.
If the account doesn't have enough credits, the call fails with insufficientCredits, and the error includes a link. Over MCP the link is the PodBox support page. Over HTTP it is the dashboard subscription page. If the file no longer fits the plan's storage, PodBox voids the episode and deletes the file.
Request
- MCP
tools/call complete_episode- HTTP
POST https://api.podbox.sh/api/v1/episodes/{episodeId}/complete
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
episodeId | string | Yes | path | The episodeId that hold_episode returned. |
Response
The episode's episodeId, status, title, description, and bytes, the stored size as a decimal string. When the file doesn't fit the plan, status is voided, reason names the limit, and fields such as quotaBytes, usedBytes, requestedBytes, and maxBytes give the sizes. A call for an episode that is already published returns only episodeId, with a status of replay.
Read episode
Gets the status of one episode.
Use this method to follow a narration from create_speech_episode until it publishes, or to check an upload after complete_episode. While a narration renders, the response includes progress. After the episode publishes, the response includes the credits it used.
You can call this method at most 5 times a second. A faster call fails with slowDown. Over REST, that response is HTTP 429 and includes retryAfterMs, the number of milliseconds to wait before you call again.
Request
- MCP
tools/call read_episode- HTTP
GET https://api.podbox.sh/api/v1/episodes/{episodeId}
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
episodeId | string | Yes | path | The ID of the episode to read. |
Response
The episode's status (held, published, voided, closed, or failed), episodeId, title, description, and bytes. The response can also include durationSeconds, the credits the episode used in generationCredits and storageCredits, the reason an episode closed (deleted, expired, aged, or trimmed), and the render progress, with phase (queued or rendering), partsDone, and partsTotal. Over REST, the response also includes audioUrl, the signed audio link the feed uses, and its mimeType. Both are null unless the episode is published and has not expired. It also includes coverUrl, the image podcast apps show for the episode: its own cover, else the show cover, else the PodBox default.
List episodes
Lists the episodes in the feed, newest first.
Use this method to find an episode's episodeId, for example before you call delete_episode. Each page holds up to 20 episodes, newest first.
To get older episodes, pass nextCursor as cursor. To get newer episodes, pass prevCursor. Cursors are opaque, so don't parse or build them.
Pages can shift when episodes are added or removed. An empty page can still carry a cursor in the other direction.
Request
- MCP
tools/call list_episodes- HTTP
GET https://api.podbox.sh/api/v1/episodes
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
cursor | string | No | query | A nextCursor or prevCursor value from an earlier page. To get the first page, leave it out. |
Response
The episodes on this page, nextCursor for older episodes, and prevCursor for newer episodes. A cursor is null when no episodes lie in its direction. Each episode has episodeId, title, status (held or published), publishedAt, durationSeconds, bytes, and expiresAt, the time it leaves the feed. Times are Unix timestamps in milliseconds. expiresAt is null for a held episode and when retention is never. Over REST, each episode also includes audioUrl and mimeType, which are null unless the episode is published and has not expired.
Update episode
Updates the title and description of an episode, and optionally its duration.
This method works on held and published episodes. It doesn't change the audio. Any other episode fails with notEditable.
Send both title and description on every call, even when only one of them changes. To keep the current duration, leave out durationSeconds.
Request
- MCP
tools/call update_episode- HTTP
PATCH https://api.podbox.sh/api/v1/episodes/{episodeId}
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
episodeId | string | Yes | path | The ID of the episode to update. |
title | string | Yes | body | The episode title in the feed, from 1 through 256 characters. |
description | string | Yes | body | The episode description, up to 4,096 characters. To leave it blank, send an empty string. |
durationSeconds | integer | No | body | The length of the audio in whole seconds, from 1 through 864,000. If you leave it out, the duration doesn't change. |
Response
The episode's episodeId, title, description, and bytes, with a status of edited or replay.
Set episode cover
Sets the cover art for one episode.
The image must be a square PNG or JPEG from 1,400 to 3,000 pixels on each side. For the best result, send a 1,400 × 1,400 pixel RGB image with no transparency, and scale a smaller image up before you send it.
An image in the wrong format fails with coverFormat, one of the wrong size fails with coverDimensions, and one that PodBox can't read fails with coverUnreadable. Setting a cover is free.
An episode with no cover of its own uses the show cover, or the default episode cover when the show has none. To set the show cover, call set_cover.
Request
- MCP
tools/call set_episode_cover- HTTP
POST https://api.podbox.sh/api/v1/episodes/{episodeId}/cover
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
episodeId | string | Yes | path | The ID of the episode. |
contentType | string | Yes | body | The image format. The image bytes must match it. One of image/jpeg, image/png. |
image | string | Yes | body | The image file, base64-encoded with no line breaks and no data: prefix. At most 1 MiB once decoded. |
Response
The status of the change, applied or replay.
Delete episode
Deletes an episode from the feed.
The episode leaves the feed right away, and PodBox deletes its audio shortly after. The credits the episode used aren't refunded.
To find the episodeId, call list_episodes.
Request
- MCP
tools/call delete_episode- HTTP
DELETE https://api.podbox.sh/api/v1/episodes/{episodeId}
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
episodeId | string | Yes | path | The ID of the episode to delete. |
Response
The deleted episode's episodeId, title, description, and bytes, with a status of closed.
Show and feed
Set the title, description, author, and cover art that podcast apps show for the feed, and get or replace the feed link.
Update show
Sets the title, description, and author of the show.
Podcast apps show these for the feed. Send all three on every call. The feed link doesn't change.
Request
- MCP
tools/call update_show- HTTP
PATCH https://api.podbox.sh/api/v1/show
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
title | string | Yes | body | The show title, up to 200 characters. |
description | string | Yes | body | The show description, up to 2,000 characters. |
author | string | Yes | body | The author name, up to 200 characters. |
Response
The show's title, description, and author after the update. Over REST, the response also includes coverUrl, the show cover or the PodBox default. GET /api/v1/show returns the same fields without a change.
Set cover
Sets the cover art for the show.
Podcast apps show the show cover for the feed and for each episode that has no cover of its own. To set the cover for one episode, call set_episode_cover.
The image must be a square PNG or JPEG from 1,400 to 3,000 pixels on each side. For the best result, send a 1,400 × 1,400 pixel RGB image with no transparency, and scale a smaller image up before you send it.
An image in the wrong format fails with coverFormat, one of the wrong size fails with coverDimensions, and one that PodBox can't read fails with coverUnreadable. Setting a cover is free.
Request
- MCP
tools/call set_cover- HTTP
POST https://api.podbox.sh/api/v1/show/cover
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
contentType | string | Yes | body | The image format. The image bytes must match it. One of image/jpeg, image/png. |
image | string | Yes | body | The image file, base64-encoded with no line breaks and no data: prefix. At most 1 MiB once decoded. |
Response
The status of the change, applied or replay.
Get feed link
Gets the private feed link for the show.
Your user subscribes by adding this link in their podcast app by URL. The link contains a secret token after /feeds/, and anyone who has the link can listen. To replace a link that leaked, call rotate_feed.
Request
- MCP
tools/call feed_url- HTTP
GET https://api.podbox.sh/api/v1/feed
Arguments
No arguments.
Response
The feed link, in url.
Replace feed link
Replaces the feed link with a new one.
The old link stops working, and anyone who subscribed with it has to subscribe again with the new link. Use this method when the link leaks or your user asks for a new one. Each call makes a new link.
If PodBox can't write the feed, the call fails with feed_rotation_incomplete and the link doesn't change. Call this method again.
Request
- MCP
tools/call rotate_feed- HTTP
POST https://api.podbox.sh/api/v1/feed/rotate
Arguments
No arguments.
Response
The new feed link, in url.
Account
Check the plan, credits, and storage of the account, and choose how long episodes stay in the feed.
Account status
Gets the plan, credits, storage, and retention setting of the account.
Call this method before you plan a recurring show, or after a publish fails, to see what the account can still do. Over MCP the response includes supportUrl, the PodBox support page. Over HTTP it includes dashboardUrl, the dashboard subscription page, instead.
Request
- MCP
tools/call account_status- HTTP
GET https://api.podbox.sh/api/v1/account
Arguments
No arguments.
Response
The account's plan (free or paid), the credits it can spend, the credits reserved for narration in progress, and creditExpiresAt, when the first of the remaining credits expire, or null when no credits remain. The storage object has standing, usedBytes, quotaBytes, usedEpisodes, and episodeLimit. The retention object has the current setting, canChange, and the options that set_retention accepts. The response also has supportUrl over MCP or dashboardUrl over HTTP, and libraryTrim when PodBox has started trimming the library of a lapsed plan. Byte counts are decimal strings, and times are Unix timestamps in milliseconds.
Set retention
Sets how long published episodes stay in the feed.
Only paid plans can change retention. Free plans keep episodes for 30 days, and a call on a free plan fails with retentionPinned. To check first, read retention.canChange from account_status.
Paid plans start at never, which keeps episodes until you delete them. When you shorten retention, PodBox removes episodes older than the new limit at its next daily sweep.
Request
- MCP
tools/call set_retention- HTTP
PATCH https://api.podbox.sh/api/v1/retention
Arguments
| Name | Type | Required | In | Description |
|---|---|---|---|---|
retention | string | Yes | body | The number of days an episode stays in the feed after it publishes, or never to keep episodes until you delete them. One of 30, 60, 180, 365, never. |
Response
The retention now in effect, change (open when the plan can change it, fixed when it can't), and status (applied or replay).
Voices
List the voices that can narrate a script.
List voices
Lists the voices that can narrate a script.
To choose a voice, play its sample. Then pass its name as voice_preset in a create_speech_episode script part.
Request
- MCP
tools/call list_speech_presets- HTTP
GET https://api.podbox.sh/api/v1/speech/presets
Arguments
No arguments.
Response
The presets. Each has kind (voice), name, and sampleUrl, a link to a sample of the voice.