PostPod API
The PostPod API is a versioned HTTP API at /api/v1. It uses bearer API keys or a signed-in access token, JSON responses, and prepaid credits for Script to audio. Daily episodes are included in Free and Pro and do not debit those credits. Listeners pick X accounts and topics. PostPod picks the posts. The machine-readable description is the OpenAPI specification. Agents should also read llms.txt. Versioning and retirement rules are the API versioning and deprecation policy.
Reference
- API rate limits lists the per-key, per-account, and per-IP caps, and how to read a 429.
- API changelog lists shipped public API changes, newest first.
- API versioning and deprecation policy is the notice period and the Deprecation, Sunset, and Link headers.
Agent quickstart
An agent can open its own PostPod account. Prepaid credits are the trust mechanism. A new account can estimate a script and buy credits. It cannot create jobs until a pack is paid.
- POST /api/v1/agent-accounts/challenge. The response includes challenge_id, a hex challenge, a difficulty, and an expiry. No API key is required. The challenge is not bound to the caller IP.
- Find a nonce such that the SHA-256 hex of challenge_id, the challenge, and the nonce, joined by colons, starts with that many zero digits.
- POST /api/v1/agent-accounts with challenge_id, nonce, name, and an optional operator_email. A different outbound IP than the challenge request is accepted. The challenge is still single-use, short-lived, and checked against the proof of work. The response includes account_id, an API key shown once, balance 0, tier new, limits, and a claim URL.
- POST /api/v1/credits/checkout with pack_usd. Give the returned Stripe URL to a human to pay by card or USDC. A card payment is credited when checkout completes as paid. USDC stays unpaid until async_payment_succeeded, which credits that same Checkout Session once. async_payment_failed adds nothing. When the webhook credits the pack, the tier becomes funded.
- POST /api/v1/credits/pay with the same pack_usd when the agent should pay without a browser. Keep Authorization: Bearer pp_live_…. A 402 WWW-Authenticate response is an MPP challenge for that pack. Retry the same body with the credential in Payment-Authorization. PostPod credits the settled USD amount once, keyed by the Stripe payment id. The route is off until machine payments are configured.
- A new or funded account can add up to $100 of packs per UTC day. A funded account can speak scripts up to 5,000 words, start 5 jobs an hour, and make 10 requests a minute.
- POST /api/v1/agent-accounts/verify-email to send a code to the operator email, then POST the code. The tier becomes verified and the daily pack cap lifts.
- POST /api/v1/agent-accounts/claim-link and have a signed-in human open /claim/<token>. The tier becomes claimed and limits match a human account. That human can POST /api/v1/credits/transfers.
- POST /api/v1/keys/rotate with the current key to replace it. The previous key stops working.
Quickstart
- Create an account at https://postpodai.com/signup and open the API page at https://postpodai.com/settings/api to create an API key. Copy it immediately. PostPod stores only a hash.
- Call GET /api/v1/account/me with Authorization: Bearer and your key. The response includes the credit balance.
- Call POST /api/v1/script-audio/estimate with a script and a voice. output_language defaults to English (en) when omitted and is validated when you send it. The response includes price_usd. That call does not spend credits.
- Buy a credit pack on the signed-in billing page if the balance is lower than the price.
- Call POST /api/v1/script-audio with the same script. The balance is debited and the job is queued.
- Poll GET /api/v1/script-audio/{id} until status is ready, then GET the download path for a temporary audio URL. The job includes progress, from 0 to 1, and optional estimated_seconds_remaining (whole seconds). That field is null when the job is not running and during the final join and encode. estimated_seconds_approximate is true while the number is still an estimate from script length and historical speed, before chunk progress can set a rate. Clients that do not use these fields can ignore them.
Script to audio quickstart
These samples estimate a short script, create the job, poll until it is ready or failed, then save the MP3. Set POSTPOD_API_KEY in the environment. Do not paste the key into the file. macOS or Linux: export POSTPOD_API_KEY='pp_live_your_key'. Windows PowerShell: $env:POSTPOD_API_KEY = 'pp_live_your_key'. The samples do not send include_intro_outro. That field is deprecated and ignored. Script to audio never adds an intro or outro. A 402 response, code insufficient_credits, means the balance is too low. Daily podcast episodes still include their intro and outro.
Python
#!/usr/bin/env python3
"""Save a Script to audio MP3. Uses the Python 3 standard library only.
macOS or Linux:
export POSTPOD_API_KEY='pp_live_your_key'
Windows PowerShell:
$env:POSTPOD_API_KEY = 'pp_live_your_key'
"""
import json
import os
import sys
import time
import urllib.error
import urllib.request
from pathlib import Path
API = "https://postpodai.com"
OUTPUT = "script.mp3"
POLL_SECONDS = 3
POLL_LIMIT = 120
def main() -> None:
key = os.environ.get("POSTPOD_API_KEY", "").strip()
if not key:
print("Set POSTPOD_API_KEY to your pp_live_ key.", file=sys.stderr)
raise SystemExit(1)
body = {
"script": "Hello from PostPod. This is a short script.",
"voice": "Nora",
"input_language": "auto",
"output_language": "en",
}
print("Estimating price...")
estimate = call("POST", "/api/v1/script-audio/estimate", key, body)
print(
f"Estimate: {estimate.get('word_count')} words, "
f"${estimate.get('price_usd')} (this call does not spend credits)"
)
print("Creating job...")
created = call("POST", "/api/v1/script-audio", key, body)
job = created["job"]
job_id = job["id"]
print(f"Job {job_id} is {job.get('status')}. Balance ${created.get('balance_usd')}")
for attempt in range(1, POLL_LIMIT + 1):
current = call("GET", f"/api/v1/script-audio/{job_id}", key)["job"]
status = current.get("status")
print(f"Poll {attempt}: {status}")
if status == "ready":
job = current
break
if status == "failed":
print(current.get("error") or "Audio failed.", file=sys.stderr)
raise SystemExit(1)
time.sleep(POLL_SECONDS)
else:
print("Timed out waiting for audio.", file=sys.stderr)
raise SystemExit(1)
print("Fetching download URL...")
download = call("GET", f"/api/v1/script-audio/{job_id}/download", key)
url = download["download_url"]
print(f"Saving {OUTPUT}")
urllib.request.urlretrieve(url, OUTPUT)
print(f"Saved {Path(OUTPUT).resolve()}")
def call(method, path, key, body=None):
data = None if body is None else json.dumps(body).encode()
headers = {"Authorization": f"Bearer {key}", "Accept": "application/json"}
if data is not None:
headers["Content-Type"] = "application/json"
request = urllib.request.Request(API + path, data=data, method=method, headers=headers)
try:
with urllib.request.urlopen(request, timeout=60) as response:
return json.loads(response.read().decode())
except urllib.error.HTTPError as error:
raw = error.read().decode("utf-8", "replace")
try:
problem = json.loads(raw)
except json.JSONDecodeError:
problem = {"message": raw}
code = str(problem.get("code") or "")
message = str(problem.get("message") or problem.get("error") or error.reason)
if error.code == 402 or code == "insufficient_credits":
print(f"Not enough credits ({code or 'insufficient_credits'}): {message}", file=sys.stderr)
topup = problem.get("top_up_url")
if topup:
print(f"Buy credits: {topup}", file=sys.stderr)
else:
print(f"HTTP {error.code} {code}: {message}", file=sys.stderr)
resolution = problem.get("resolution")
if resolution:
print(resolution, file=sys.stderr)
raise SystemExit(1)
if __name__ == "__main__":
main()
# Accepted script files for POST /api/v1/script-audio/extract are .txt, .md, .docx, and .pdf.
# Send multipart form field "file" and voice Nora, Leo, Kristine, Ken, or Marko.
# The response is the extracted text, word count, and price. It does not create a job or spend credits.
curl on macOS or Linux
# macOS or Linux
set -eu
export POSTPOD_API_KEY='pp_live_your_key'
BASE="https://postpodai.com"
BODY='{"script":"Hello from PostPod. This is a short script.","voice":"Nora","input_language":"auto","output_language":"en"}'
echo "Estimating price..."
curl -sS -f -H "Authorization: Bearer $POSTPOD_API_KEY" \
-H "Content-Type: application/json" \
-d "$BODY" \
"$BASE/api/v1/script-audio/estimate"
echo
echo "Creating job..."
curl -sS -H "Authorization: Bearer $POSTPOD_API_KEY" \
-H "Content-Type: application/json" \
-d "$BODY" \
"$BASE/api/v1/script-audio" -o create.json
python3 -c 'import json,sys; body=json.load(open("create.json"));
code=body.get("code");
sys.exit(print("Not enough credits:", body.get("message"), body.get("top_up_url") or "") or 1) if body.get("status")==402 or code=="insufficient_credits" else None;
print("Job", body["job"]["id"], body["job"].get("status"))'
JOB_ID=$(python3 -c 'import json; print(json.load(open("create.json"))["job"]["id"])')
echo "Polling $JOB_ID..."
while true; do
curl -sS -f -H "Authorization: Bearer $POSTPOD_API_KEY" \
"$BASE/api/v1/script-audio/$JOB_ID" -o job.json
STATUS=$(python3 -c 'import json; print(json.load(open("job.json"))["job"]["status"])')
echo "Status: $STATUS"
if [ "$STATUS" = "ready" ]; then
break
fi
if [ "$STATUS" = "failed" ]; then
python3 -c 'import json,sys; print(json.load(open("job.json"))["job"].get("error") or "Audio failed.", file=sys.stderr)'
exit 1
fi
sleep 3
done
echo "Fetching download URL..."
curl -sS -f -H "Authorization: Bearer $POSTPOD_API_KEY" \
"$BASE/api/v1/script-audio/$JOB_ID/download" -o download.json
URL=$(python3 -c 'import json; print(json.load(open("download.json"))["download_url"])')
curl -fsSL "$URL" -o script.mp3
echo "Saved script.mp3"
# Preview a file without creating a job. Accepted types: .txt, .md, .docx, .pdf
# curl -sS -f -H "Authorization: Bearer $POSTPOD_API_KEY" \
# -F "file=@script.pdf" -F "voice=Nora" \
# "$BASE/api/v1/script-audio/extract"
curl on Windows PowerShell
# Windows PowerShell. curl is curl.exe, not Invoke-WebRequest.
$env:POSTPOD_API_KEY = 'pp_live_your_key'
$base = "https://postpodai.com"
$body = @'
{"script":"Hello from PostPod. This is a short script.","voice":"Nora","input_language":"auto","output_language":"en"}
'@
Write-Host "Estimating price..."
curl.exe -sS -f -H "Authorization: Bearer $env:POSTPOD_API_KEY" `
-H "Content-Type: application/json" `
-d $body `
"$base/api/v1/script-audio/estimate"
Write-Host ""
Write-Host "Creating job..."
curl.exe -sS -H "Authorization: Bearer $env:POSTPOD_API_KEY" `
-H "Content-Type: application/json" `
-d $body `
"$base/api/v1/script-audio" -o create.json
$created = Get-Content create.json -Raw | ConvertFrom-Json
if ($created.status -eq 402 -or $created.code -eq "insufficient_credits") {
Write-Error "Not enough credits: $($created.message) $($created.top_up_url)"
exit 1
}
$jobId = $created.job.id
Write-Host "Job $jobId is $($created.job.status)"
Write-Host "Polling $jobId..."
while ($true) {
curl.exe -sS -f -H "Authorization: Bearer $env:POSTPOD_API_KEY" `
"$base/api/v1/script-audio/$jobId" -o job.json
$job = (Get-Content job.json -Raw | ConvertFrom-Json).job
Write-Host "Status: $($job.status)"
if ($job.status -eq "ready") { break }
if ($job.status -eq "failed") {
if ($job.error) { Write-Error $job.error } else { Write-Error "Audio failed." }
exit 1
}
Start-Sleep -Seconds 3
}
Write-Host "Fetching download URL..."
curl.exe -sS -f -H "Authorization: Bearer $env:POSTPOD_API_KEY" `
"$base/api/v1/script-audio/$jobId/download" -o download.json
$url = (Get-Content download.json -Raw | ConvertFrom-Json).download_url
curl.exe -fsSL $url -o script.mp3
Write-Host "Saved script.mp3"
# Preview a file without creating a job. Accepted types: .txt, .md, .docx, .pdf
# curl.exe -sS -f -H "Authorization: Bearer $env:POSTPOD_API_KEY" `
# -F "file=@script.pdf" -F "voice=Nora" `
# "$base/api/v1/script-audio/extract"
Authentication
Send Authorization: Bearer on every /api/v1 route except the index. A pp_live_ key from the API page at https://postpodai.com/settings/api works as before. A signed-in access token for the same user also works. PostPod checks that token with the auth server and does not accept an unverified token. Key rotation and credit pack purchase stay on the pp_live_ key. A revoked key returns 401. Each human key, and each signed-in session, is limited to 60 requests per minute unless the deployment sets a different API_RATE_LIMIT_PER_MINUTE. The session uses its own counter. An agent key uses its trust-tier limit, and a signed-in agent session uses that same tier. A response that evaluated a limiter includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds when the window resets), plus the RateLimit-Policy and RateLimit headers. A limited request returns 429 and a Retry-After header, in seconds. GET /api/v1 does not evaluate a limiter and omits those headers. Challenge requests and signup attempts are limited per IP, and creating an account also checks how many accounts that network opened in the signup window.
Endpoints
- GET /api/v1 returns links to these docs and the OpenAPI file. No key is required.
- GET /api/v1/account/me returns the account id, email, plan, kind, tier, limits, today's usage, and credit balance. DELETE /api/v1/account deletes that account. The JSON body must be {"confirm":"DELETE"}. Anything else is 400. An active subscription is canceled immediately and is not refunded. The show, episodes, audio, Script to audio jobs, API keys, and push tokens are deleted. Stripe keeps the customer and invoices. An allowlisted admin account is 403. Success is 204 with no body.
- POST /api/v1/push-tokens saves an Expo push token for the signed-in account. The body is token, platform ios, and an optional device_name. token must be ExponentPushToken[...] or ExpoPushToken[...]. DELETE /api/v1/push-tokens with {token} removes that token. A missing bearer token is 401. POST success returns the saved token. DELETE success is 204.
- GET and POST /api/v1/shows list or create the show. PATCH /api/v1/shows/{id} updates it. A show has X accounts (handles) and topics (news, sports, ai, finance, crypto). topic_apply replace or add fills accounts from those topics. Free can follow 3 accounts. Pro can follow 25. The limits match the website, including one show per account. language defaults to English (en) when omitted or blank. Free accounts stay English only. Pro can send any supported language. Omit topics to leave stored topics unchanged.
- POST /api/v1/shows/{id}/episodes starts today's episode with the same rules as the website Generate button. Free is one episode per delivery day. A ready episode is not generated again. A deleted episode stays deleted. The response includes the episode id and status. Poll GET /api/v1/episodes/{id}. discard_script true drops the saved draft. This does not debit prepaid credits.
- GET /api/v1/episodes and GET /api/v1/episodes/{id} read daily episodes. DELETE /api/v1/episodes/{id} deletes one episode the same way the website Library does: the row stays with status deleted, the script is cleared, and the audio file is removed. A missing bearer token is 401. An episode that is not this account's, or that does not exist, is 404. Success is 204 with no body, including when it was already deleted. An episode that is still generating is 409. That delivery day is not generated again. An allowlisted admin can still reopen that same row from Generate now. GET /api/v1/episodes/{id}/audio returns a temporary MP3 URL when the episode is ready and still inside 30 days. After that the response is 410 with code expired.
- POST /api/v1/script-audio/estimate prices a script. POST /api/v1/script-audio creates a job. An Idempotency-Key header retries that create without a second debit. The same script, voice, and languages within two minutes also return the original job. A 409 means a job is still running, or this script was just submitted; send X-Script-Audio-Confirm: another to pay for another one. script_audio_active includes job_id and job_url. The message says you have already paid only when that job was charged. Otherwise it says you already have audio being made. GET lists and fetches jobs, including queued and generating jobs, progress, and estimated_seconds_remaining. GET /api/v1/script-audio/{id}/download returns a temporary MP3 URL inside 30 days. After that the response is 410 with code expired.
- POST /api/v1/script-audio/extract reads a .txt, .md, .docx, or .pdf file up to 2 MB and returns the text, word count, and price. It does not create a job and does not spend credits. POST /api/v1/script-audio/estimate accepts that same file when you only need the price. Password-protected PDFs and scans are rejected. The file is not stored. Send the extracted text to POST /api/v1/script-audio to create the job.
- POST /api/v1/agent-accounts/challenge and POST /api/v1/agent-accounts create an agent account. POST /api/v1/credits/checkout returns a Stripe pack link. POST /api/v1/credits/pay buys a pack with an MPP challenge. POST /api/v1/credits/transfers moves credits to a claimed agent.
Voices and languages
Send the voice as a display name or as its lowercase id: nora, leo, kristine, ken, or marko. Deprecated voice ids are still accepted and are not returned: stock-nora → nora, stock-reed → leo, stock-sienna → kristine, stock-kai → ken, stock-mira → marko. Responses use the current id. Nora is available on the free plan for the daily show. The other narrators require Pro for the daily show. Script to audio accepts any of the five names. GET /api/v1 lists each voice with its description and gender. Gender is confirmed by PostPod owner. Show language on POST and PATCH /api/v1/shows uses the same language list as the website and defaults to English (en) when omitted or blank. Free shows stay English only. Pro shows can use any supported language. input_language is auto or a language code. output_language is a language code and defaults to English (en) when omitted. A code that is sent must be one of the supported languages. include_intro_outro is deprecated and ignored. Script to audio never adds an intro or outro.
- Nora — Clear single-narrator voice (free tier). Gender: female.
- Leo — Warm mid-range narrator (Pro). Gender: male.
- Kristine — Bright conversational narrator (Pro). Gender: female.
- Ken — Low, even newsreader (Pro). Gender: male.
- Marko — Crisp international narrator (Pro). Gender: male.
Credits
Script to audio API jobs spend prepaid credits. Packs are $5, $10, $20, $50, $100 USD. A signed-in user buys a pack on the billing page by card or by USDC stablecoin, and an API key can POST /api/v1/credits/checkout to get a Stripe link a human pays the same way. USDC uses Stripe's crypto payment method and settles to USD. The API does not take a card number or a wallet. Creating a job debits the price_usd returned by the estimate endpoint for that same script. The minimum price is $1. If the balance is too low, the response is HTTP 402 with code insufficient_credits and a top_up_url. If generation fails, the debit is returned to the balance. A pack is credited once. A later USDC settlement uses the same Checkout Session and does not credit the pack again. A failed stablecoin payment adds nothing. A human who has claimed an agent can move credits to it with POST /api/v1/credits/transfers. The same idempotency key does not move the credits twice. Daily spend is the ledger total leaving the account that UTC day. An API key whose account email is on ADMIN_EMAILS does not debit credits and does not return 402 for a zero balance. The estimate keeps price_usd and adds amount_due_usd 0. POST /api/v1/credits/pay is the agent path for the same packs. It returns HTTP 402 with an MPP challenge, then credits only the settled amount. That 402 is not insufficient_credits. The route is off until machine payments are configured.
Versioning
The current version is v1 in the URL path. Breaking changes ship only in a new version. The API versioning and deprecation policy is the notice period, the dated announcements, and the Deprecation, Sunset, and Link headers.
Errors
Errors use application/problem+json. Each body includes code, message, and resolution, plus the RFC 9457 fields type, title, status, and detail. title is a short label, such as Unauthorized on a 401, and detail is the specific sentence. The message repeats that sentence, and it is also copied to error for older clients. Common codes are invalid_api_key (401), insufficient_credits (402), not_found (404), validation_error (422), rate_limit_exceeded (429), and feature_disabled (404) when Script to audio is turned off. Agent signup uses signup_rate_limited (429), proof_of_work_expired (422), proof_of_work_used (422), and proof_of_work_failed (422). A changed caller IP is not one of those errors.
MCP
PostPod also serves a remote MCP server at /api/mcp. The transport is Streamable HTTP, and each response is JSON. initialize, notifications/initialized, ping, and tools/list do not need a key. tools/list returns a static catalog and does not read an account. resources/list and prompts/list do not need a key either. Calling a tool, or any other method, needs the same Authorization: Bearer pp_live_… key you use for /api/v1. A missing or rejected key on that call is HTTP 401 with code invalid_api_key. Scopes, plan limits, rate limits, and prepaid credits are the same checks as the HTTP API. One authenticated MCP request counts as one API request. Unauthenticated discovery is rate limited per IP.
Tools read the account, list and update the show, list episodes, start today's episode, and return a temporary audio URL. The listener chooses X accounts and topics. PostPod picks the posts. Estimating a script does not spend credits. Creating a Script to audio job spends prepaid credits the same way POST /api/v1/script-audio does. generate_episode uses the same Free and Pro limits as the website and does not debit prepaid credits. Tool calls still need a pp_live_ key. A signed-in access token is for /api/v1, not for /api/mcp. File upload, credit checkout, credit transfer, agent signup, and key rotation stay on /api/v1.
Cursor
{
"mcpServers": {
"postpod": {
"url": "https://postpodai.com/api/mcp",
"headers": {
"Authorization": "Bearer pp_live_your_key"
}
}
}
}Claude
{
"mcpServers": {
"postpod": {
"type": "http",
"url": "https://postpodai.com/api/mcp",
"headers": {
"Authorization": "Bearer pp_live_your_key"
}
}
}
}Other clients use that same URL and bearer header. Replace pp_live_your_key with a key from the API page (/settings/api). The key is a secret. Do not commit it.
Support
Questions about the API: hello@postpodai.com.
