Skip to content

Resources

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

create_speech_episode Safe to retry

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

NameTypeRequiredInDescription
titlestringYesbodyThe episode title in the feed, from 1 through 256 characters.
descriptionstringYesbodyThe episode description, up to 4,096 characters. To leave it blank, send an empty string.
idempotencyKeystringYesbodyA key you choose for this episode, from 1 through 200 characters with no whitespace. Send the same key when you retry the same request.
scriptarrayYesbodyThe parts of the script, in the order they play. From 1 through 8 parts. Each item is one of these objects:
  • {text, voice_preset}
    • text (string). The text to narrate, up to 50,000 characters. PodBox trims whitespace from both ends, and the text can't be empty.
    • voice_preset (string). The voice that reads text. To hear a sample of each voice, call list_speech_presets. One of american-female-heart, american-male-puck.
  • {silence_ms}
    • silence_ms (integer). The length of a pause in milliseconds, from 1 through 10,000.

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

hold_episode Safe to retry

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

NameTypeRequiredInDescription
titlestringYesbodyThe episode title in the feed, from 1 through 256 characters.
descriptionstringYesbodyThe episode description, up to 4,096 characters. To leave it blank, send an empty string.
contentTypestringYesbodyThe 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.
bytesintegerYesbodyThe exact size of the file in bytes, up to 1 GiB.
idempotencyKeystringYesbodyA key you choose for this episode, from 1 through 200 characters with no whitespace. Send the same key when you retry the same request.
durationSecondsintegerNobodyThe 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

complete_episode Safe to retry

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

NameTypeRequiredInDescription
episodeIdstringYespathThe 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

read_episode Read-only

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

NameTypeRequiredInDescription
episodeIdstringYespathThe 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

list_episodes Read-only

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

NameTypeRequiredInDescription
cursorstringNoqueryA 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

update_episode Safe to retry

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

NameTypeRequiredInDescription
episodeIdstringYespathThe ID of the episode to update.
titlestringYesbodyThe episode title in the feed, from 1 through 256 characters.
descriptionstringYesbodyThe episode description, up to 4,096 characters. To leave it blank, send an empty string.
durationSecondsintegerNobodyThe 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

set_episode_cover Repeats on retry

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

NameTypeRequiredInDescription
episodeIdstringYespathThe ID of the episode.
contentTypestringYesbodyThe image format. The image bytes must match it. One of image/jpeg, image/png.
imagestringYesbodyThe 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

delete_episode Deletes, safe to retry

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

NameTypeRequiredInDescription
episodeIdstringYespathThe 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

update_show Safe to retry

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

NameTypeRequiredInDescription
titlestringYesbodyThe show title, up to 200 characters.
descriptionstringYesbodyThe show description, up to 2,000 characters.
authorstringYesbodyThe 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

set_cover Repeats on retry

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

NameTypeRequiredInDescription
contentTypestringYesbodyThe image format. The image bytes must match it. One of image/jpeg, image/png.
imagestringYesbodyThe 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

feed_url Read-only

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

rotate_feed Repeats on retry

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

account_status Read-only

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

set_retention Safe to retry

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

NameTypeRequiredInDescription
retentionstringYesbodyThe 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

list_speech_presets Read-only

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.