# PostPod > A personalized daily AI podcast from the X and Twitter accounts and topics you choose. No X account needed. Free and Pro. PostPod makes a personalized daily AI podcast from the X and Twitter accounts and topics you choose. You pick the accounts or topics, a narrator, and the time of day. You do not need an X account. PostPod picks the posts. It also turns a script you already wrote into an MP3. The episode is an audio file you can play in your library. ## When to use PostPod Use PostPod when an agent or a person needs a personalized daily AI podcast from the X and Twitter accounts and topics you choose, or needs an existing script turned into an MP3 with a named narrator. - Build a daily audio episode from the recent posts of X accounts the listener chooses. - Speak a finished script with Nora, Leo, Kristine, Ken, or Marko. Script to audio does not add an intro or outro. - Check a credit balance, estimate a script price, and create a Script to audio job over HTTP. ## When not to use PostPod - Do not use PostPod to post, like, or reply on X. It only reads accounts the listener configures. - Do not use PostPod for live conversation, music beds, or a public podcast directory. - Do not send card numbers or a wallet private key to the API. A human pays a credit pack by card or USDC through a Stripe Checkout link. An agent pays a pack with POST /api/v1/credits/pay and an MPP challenge. ## Links - [Developer docs](https://postpodai.com/developers) - [API rate limits](https://postpodai.com/developers/rate-limits) - [API changelog](https://postpodai.com/developers/changelog) - [API versioning and deprecation policy](https://postpodai.com/developers/deprecation) - [OpenAPI specification](https://postpodai.com/openapi.json) - [Full agent guide](https://postpodai.com/llms-full.txt) - [MCP server](https://postpodai.com/api/mcp) (Streamable HTTP; discovery is open, tool calls use a bearer API key) - [Pricing](https://postpodai.com/pricing) - [About](https://postpodai.com/about) - [Contact](https://postpodai.com/contact) ([hello@postpodai.com](mailto:hello@postpodai.com)) - [Privacy](https://postpodai.com/privacy) - [Sitemap](https://postpodai.com/sitemap.xml) A human signs up at https://postpodai.com/signup and can call /api/v1 with a signed-in access token or with a bearer API key from https://postpodai.com/settings/api. The access token is checked with the auth server. DELETE /api/v1/account with {"confirm":"DELETE"} deletes that account, cancels an active subscription immediately without a refund, and removes the show, episodes, audio, Script to audio jobs, and API keys. Stripe keeps the customer and invoices. An allowlisted admin account is refused. Key rotation and credit pack purchase stay on the pp_live_ key. POST /api/v1/shows/{id}/episodes starts today's episode with the same Free and Pro rules as the website, including one episode per delivery day. It does not debit prepaid credits. A show stores X accounts and topics (news, sports, ai, finance, crypto). Free follows 3 accounts. Pro follows 25. Listeners pick accounts and topics. PostPod picks the posts. An agent can also POST /api/v1/agent-accounts/challenge and POST /api/v1/agent-accounts to open its own account. The challenge is single-use and short-lived, and it is not tied to the caller IP. Challenge requests and signup attempts are still rate limited per IP. Script to audio jobs spend prepaid credits. GET /api/v1/script-audio/{id} includes progress and optional estimated_seconds_remaining. A repeated Idempotency-Key on create does not debit twice. An API key whose account email is on ADMIN_EMAILS is not charged, is not limited by the hourly job cap, the daily spend cap, or the script word cap, and still has the per-minute request cap. The estimate keeps price_usd and sets amount_due_usd to 0. Show language defaults to English (en) when a create or update omits it. Free shows stay English only. Pro shows can use any supported language. output_language defaults to English (en) when a request omits it. input_language stays auto unless a code is sent. include_intro_outro is deprecated and ignored. Script to audio never adds an intro or outro. Daily podcast episodes still include their intro and outro. A new agent can estimate and buy credits. Funded, verified, and claimed tiers raise the limits. Credit packs can be paid by card or by USDC stablecoin. An agent with an API key can POST /api/v1/credits/pay for a fixed pack. That route answers HTTP 402 with an MPP challenge, then credits the settled USDC amount once after the wallet pays and the request is retried. New and funded agents can add $100 of packs per UTC day. POST /api/v1/script-audio/extract accepts 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. A PDF must contain real text. Password-protected PDFs and scans are rejected. The website shows the extracted text so it can be edited before audio is created. Voices on that request are Nora, Leo, Kristine, Ken, and Marko. ## Script to audio quickstart Set POSTPOD_API_KEY in the environment. 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. ### Python ```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 ```bash # 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 ```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" ``` Episode scripts, episode audio, and cached posts from X are deleted after 30 days. A delivery-day row without the script stays so that day is not generated again. Script to audio MP3s are deleted after 30 days. The script job row and its payment record stay. The current API version is v1 in the URL path. Breaking changes ship only in a new version. Additive changes can happen within v1. A retired version, endpoint, or field gets at least 6 months' notice on the deprecation policy page, with Deprecation and Sunset response headers and Link rel="deprecation". Voice ids that are not the lowercase display name are deprecated. 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. When a request evaluates a rate limiter, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds when the window resets), RateLimit-Policy, and RateLimit. A 429 response also includes Retry-After in seconds. Those values come from the limiter that ran. GET /api/v1 does not evaluate a limiter and does not send the headers. ## Voices Gender is confirmed by PostPod owner. Voice ids are the lowercase display names. 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 — 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. ## MCP Remote MCP server (Streamable HTTP): https://postpodai.com/api/mcp. initialize, ping, and tools/list do not need a key. tools/list returns a static catalog. Tool calls need Authorization: Bearer with a pp_live_ API key. A signed-in access token is not accepted here. A missing or rejected key on a tool call is HTTP 401 with code invalid_api_key. One authenticated HTTP request counts as one API request. The key's scopes, plan limits, rate limit, and prepaid credits still apply to tool calls. Unauthenticated discovery is rate limited per IP. The listener chooses X accounts and topics. PostPod picks the posts. Tools read the account, shows, episodes, and audio, can start today's episode with generate_episode, can delete one with delete_episode, and can price or create Script to audio. Creating a script job spends prepaid credits. generate_episode and delete_episode do not. delete_episode leaves the same delivery-day tombstone as the website. generate_episode uses the same Free and Pro limits as the website. Cursor: ```json { "mcpServers": { "postpod": { "url": "https://postpodai.com/api/mcp", "headers": { "Authorization": "Bearer pp_live_your_key" } } } } ``` Claude: ```json { "mcpServers": { "postpod": { "type": "http", "url": "https://postpodai.com/api/mcp", "headers": { "Authorization": "Bearer pp_live_your_key" } } } } ``` AgentWebMap verification: awm_047015f6d37e931c1649ed9fab2ffe3052934d63edf75b65 # PostPod pricing PostPod is a personalized daily AI podcast from the X and Twitter accounts and topics you choose. No X account needed. Pro is $25/month USD, billed monthly as a Stripe subscription. ## Free Free - 1 show - Up to 3 handles - English only - 1 voice (Nora) - 1 episode / day - Max length 3 minutes - 30-day episode retention Start: https://postpodai.com/signup ## Pro $25/month (USD · monthly Stripe subscription) - 1 show included - Extra shows are a paid add-on - Up to 25 handles - Multiple languages - 5 voices (Nora, Leo, Kristine, Ken, Marko) - About 15 minutes - 30-day episode retention - Top global: English, Chinese, Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, Urdu, Indonesian, German, Japanese, Swahili, Turkish, Vietnamese, Korean, Italian, Persian, Thai, Filipino - Major Europe: Polish, Dutch, Swedish, Romanian, Greek, Czech, Hungarian, Ukrainian, Norwegian, Danish, Finnish, Croatian, Serbian, Bulgarian, Slovak, Slovenian, Lithuanian, Latvian, Estonian, Albanian, Macedonian, Maltese, Irish, Icelandic, Bosnian, Catalan Start: https://postpodai.com/signup?next=/settings/billing # About PostPod PostPod makes a personalized daily AI podcast from the X and Twitter accounts and topics you choose. Pick news accounts or news topics and it is a daily AI news podcast. You can also pick any public accounts or topics, and you do not need an X account. It is also for people who already have a script and want it read aloud. It is a single-narrator audio product. It is not a social network and it does not publish a public podcast catalog. ## What you configure You name the show, choose topics or X handles, pick a language and a narrator, and choose a delivery time in your timezone. The daily job picks recent posts from those accounts, writes a personalized AI podcast script, and stores an MP3 on the episode. You can play it in the library. Free accounts use English and Nora, with a short episode and a small number of handles. Pro accounts can use more handles, more languages, and the full narrator list: Nora, Leo, Kristine, Ken, and Marko. ## Script to audio If you already wrote the words, Script to audio speaks them. You can paste the script or upload a .txt, .md, .docx, or .pdf file up to 2 MB on the website and pay per script, or you can send it through the API and pay with prepaid credits. A PDF is read for text and shown so you can edit it before you pay. A scanned PDF is rejected. The website estimate and the API debit use the same price. A failed API job returns that amount to the credit balance. ## What PostPod does not do - It does not post, like, or reply on X. - It does not offer a live chat or a phone line. - It does not sell the listener's show as a public directory listing. ## Who operates it The public legal name, street address, and phone number are not published in this product yet. TODO: legal entity name. TODO: street address, TODO: city, TODO: region TODO: postal code, TODO: country. Questions about the product can be read on the [contact page](https://postpodai.com/contact). Data handling is described on the [privacy page](https://postpodai.com/privacy). # Contact us Questions, feedback, or press? Email us and we'll get back to you. [hello@postpodai.com](mailto:hello@postpodai.com) # Privacy This page describes the data the PostPod application stores so you can judge the product. It is not a lawyer-reviewed policy. The controller's legal name and address are not published yet. ## Account Signup uses email and a password through the authentication provider. The profile stores a display name and whether you want a ready-episode email. The ready-episode email preference defaults to on and can be changed with the show settings. The iOS app can save an Expo push token so that device can be notified when an episode is ready. Deleting the account removes those tokens. ## Show and episodes A show stores the podcast name, the X handles you enter, the language, the narrator, the timezone, and the delivery time. Episodes store the script, the audio file location, the length, the status, and an error when generation fails. After 30 days the script, the error text, and the audio file are deleted. The episode row stays without that content so the same day is not generated again. Cached posts from X are kept so a repeated run does not have to read them again, and rows older than 30 days are deleted. ## Script to audio, keys, and credits A Script to audio job stores the script you submit, a short preview, the language, the narrator, the price, and the audio until it expires after 30 days. A .txt, .md, .docx, or .pdf upload is read for its text. The file is not stored. API keys are stored as a SHA-256 hash plus a short prefix and the name you chose. The full key is shown once and is not stored. The credit ledger stores pack purchases, debits, and refunds with the resulting balance. Stripe stores the card payment. PostPod stores the Stripe customer id and the subscription status, not the card number. ## Who else processes it The application stores accounts and database rows, uses Stripe for subscriptions and one-time payments, a model provider to write and translate scripts, a speech provider to synthesize audio, object storage for MP3 files, an email provider for the ready-episode message, and Expo's push service when the iOS app has registered a token. X is called only to read posts for the handles on your show. ## Deleting your account You can delete the account in the app, or from the Delete account section on the billing page. The app calls DELETE /api/v1/account with a bearer API key or a signed-in access token. The body must be {"confirm":"DELETE"}. PostPod cancels an active subscription immediately and does not refund it. It then deletes the show, the X accounts and topics you picked, episodes and their audio, Script to audio files, API keys, and the account. Stripe keeps the customer and the invoices. Cached X posts that other shows may reuse are not deleted. After the account is deleted, PostPod emails that address to confirm. An allowlisted admin account cannot be deleted this way. ## Controller Replace these placeholders before relying on this page as a legal notice. TODO: legal entity name. [hello@postpodai.com](mailto:hello@postpodai.com). TODO: phone number. TODO: street address, TODO: city, TODO: region TODO: postal code, TODO: country. # 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](https://postpodai.com/openapi.json). Agents should also read [llms.txt](https://postpodai.com/llms.txt). Versioning and retirement rules are the [API versioning and deprecation policy](https://postpodai.com/developers/deprecation). ## Reference - [API rate limits](https://postpodai.com/developers/rate-limits) lists the per-key, per-account, and per-IP caps, and how to read a 429. - [API changelog](https://postpodai.com/developers/changelog) lists shipped public API changes, newest first. - [API versioning and deprecation policy](https://postpodai.com/developers/deprecation) 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/. 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](https://postpodai.com/signup) and open the API page at [https://postpodai.com/settings/api](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 ```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 ```bash # 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 ```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](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](https://postpodai.com/developers/deprecation) 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 ```json { "mcpServers": { "postpod": { "url": "https://postpodai.com/api/mcp", "headers": { "Authorization": "Bearer pp_live_your_key" } } } } ``` ### Claude ```json { "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](mailto:hello@postpodai.com). # API versioning and deprecation policy The current PostPod API version is v1. The version is in the URL path, /api/v1. This page is the public policy for how that version changes and how a later version would be retired. ## What can change inside v1 Additive changes can happen within v1. PostPod can add optional request fields, optional response fields, new endpoints, and new error codes without a new version. Clients should ignore response fields they do not use. A documented enum can gain a value only when the contract already says the list can grow. Breaking changes ship only in a new version. A breaking change removes or renames a documented field, changes the meaning or type of a field, makes an optional input required, or removes an endpoint. That work is published at a new path such as /api/v2. It is not applied silently to /api/v1. ## Notice before a version is retired When a version is retired, PostPod gives at least 6 months' notice. That length is the published default and PostPod may change it. The number stated on this page is the notice that applies. During the notice period the old version keeps working. Individual fields or endpoints get the same notice before they are removed or renamed. Notice goes out in three places. This page gets a dated announcement that names the affected version, endpoint, or field, the replacement, and the sunset date. Responses for the affected version send a Deprecation header (RFC 9745) set to the announcement time as a structured-field date, and a Sunset header (RFC 8594) set to the HTTP date when it stops working. Those responses also send Link: ; rel="deprecation". ## Current announcements Voice ids that are not the lowercase display name are deprecated as of 2026-10-29. Current ids are nora, leo, kristine, ken, and 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. These aliases stay accepted for at least 6 months from 2026-10-29. v1 is the current version. v1 responses do not send Deprecation or Sunset headers for this alias. The notice is this page, the developer docs, and the OpenAPI description. The helper that would set those headers is not active on any route. Start with the [developer docs](https://postpodai.com/developers), the [API rate limits](https://postpodai.com/developers/rate-limits), the [API changelog](https://postpodai.com/developers/changelog), the [OpenAPI specification](https://postpodai.com/openapi.json), and [llms.txt](https://postpodai.com/llms.txt). # API rate limits These are the limits the /api/v1 handlers enforce. A number that an environment variable can replace is the default. The response headers report the limiter that actually ran. They are not a second copy of this page. ## Requests per key Each API key has its own request counter. bump_api_rate_limit stores that counter in a fixed clock minute (date_trunc of the current minute). The window is 60 seconds. The policy name is api-key. A human key defaults to 60 requests per minute. API_RATE_LIMIT_PER_MINUTE can replace that default. A missing value, a non-numeric value, or a value outside 1 to 10000 keeps 60. A human key has no hourly Script to audio job cap. A signed-in access token uses the same number, stored by bump_session_rate_limit. The policy name is api-session. That counter is not the key's counter. Apply supabase/migrations/034_show_topics_and_session_rate.sql before a session can be counted. API keys keep using bump_api_rate_limit. An agent key uses its trust tier. A requests_per_minute or jobs_per_hour value stored on the agent account replaces that tier field. The tier defaults are: - new: 10 requests per minute. jobs_per_hour is 0, so creating a Script to audio job is refused before the hourly job counter runs. - funded: 10 requests per minute and 5 Script to audio jobs per hour. - verified: 30 requests per minute and 30 Script to audio jobs per hour. - claimed: 60 requests per minute and no hourly Script to audio job cap. ## Script to audio jobs Job creation is counted per account, on user id, for script_jobs created in the last 3600 seconds. It is not counted per API key. The policy name is script-jobs. The cap is the account's jobs_per_hour. When that value is null, or 0, this limiter is not evaluated. A script that exceeds the account word limit is rejected first, and that response does not include this policy. A funded account defaults to 5 jobs per hour. A verified account defaults to 30. A key whose account email is on ADMIN_EMAILS does not evaluate the hourly job cap, the daily spend cap, or the account word cap. The per-key requests-per-minute cap still applies. POST /api/v1/script-audio for that key does not add the script-jobs policy. ## Verification emails POST /api/v1/agent-accounts/verify-email can send 5 codes per account per 3600 seconds. The count is rows in agent_email_codes for that account in the sliding hour. This number is the EMAIL_SENDS_PER_HOUR constant, not an environment variable. The policy name is verification-emails. Submitting a code on the same route does not evaluate this send cap. ## Signup per IP Challenge requests and account-creation attempts use bump_agent_signup_rate, one fixed bucket per IP hash. A window shorter than 60 seconds is stored as 3600 seconds. A window longer than 604800 seconds is stored as 604800 seconds. The defaults sit inside that range. Created accounts use a separate sliding count of agent_accounts for that IP hash. The defaults are: - Challenges: 10 requests per 3600 seconds. AGENT_SIGNUP_CHALLENGE_IP_LIMIT and AGENT_SIGNUP_CHALLENGE_WINDOW_SEC can replace the defaults. The policy name is signup-challenges. - Signup attempts: 10 requests per 3600 seconds, in a different bucket from challenges. AGENT_SIGNUP_ATTEMPT_IP_LIMIT and AGENT_SIGNUP_ATTEMPT_WINDOW_SEC can replace the defaults. The policy name is signup-attempts. - Accounts created: 3 accounts per 86400 seconds. AGENT_SIGNUP_ACCOUNT_IP_LIMIT and AGENT_SIGNUP_ACCOUNT_WINDOW_SEC can replace the defaults. The policy name is signup-accounts. ## Headers A response that evaluated a limiter sends X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Reset is the Unix epoch second when that window resets. It also sends RateLimit-Policy and RateLimit. Policy is the quoted name, q for the limit, and w for the window in seconds. RateLimit is the quoted name, r for remaining, and t for seconds until reset. When more than one policy was evaluated, those two headers list every policy. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After describe the first exhausted policy, or the first policy when none is exhausted. Retry-After is sent only on 429, and only in seconds. The API does not set CORS headers, so it does not list these names in Access-Control-Expose-Headers. ## Which responses include them Authenticated /api/v1 routes include the api-key policy after bump_api_rate_limit runs, on success and on later errors from that same request. POST /api/v1/script-audio adds script-jobs when that quota is evaluated. The verify-email send path adds verification-emails after that count runs. POST /api/v1/agent-accounts/challenge includes signup-challenges after that check. POST /api/v1/agent-accounts includes signup-attempts after that check, and signup-accounts after the account-cap query succeeds. POST /api/v1/credits/pay adds machine-topups after the api-key check. That window is 5 attempts per minute. A 402 payment challenge counts. These responses do not include the headers, because no limiter ran: GET /api/v1, POST /api/v1, an unknown /api/v1 path, and an unsupported method. A 401 for a missing, invalid, revoked, or expired key does not include them. A 403 for a frozen account or an insufficient scope, when that check happens before the counter, does not include them. A 500 or 503 from the rate-limit RPC does not include them. ## Handling 429 Wait the number of seconds in Retry-After, then send the request again. Do not retry before that delay. X-RateLimit-Reset is the Unix time when the window that rejected the request resets. The problem body can also include retry_after_sec for the same wait. Per-key rejection uses rate_limit_exceeded. An hourly job rejection uses job_rate_limited. Signup rejection uses signup_rate_limited. A verification-email rejection uses rate_limit_exceeded. Daily spend caps and daily pack caps are account limits. They are not these request windows. Read the [developer docs](https://postpodai.com/developers), the [API changelog](https://postpodai.com/developers/changelog), and the [API versioning and deprecation policy](https://postpodai.com/developers/deprecation). # API changelog This page lists public API changes that have shipped on main. Dates are the merge dates. Newest entries are first. Work that is still in review is not listed. ## 2026-11-13 — Delete account DELETE /api/v1/account deletes the signed-in account after the body {"confirm":"DELETE"}. An active subscription is canceled immediately and is not refunded. Shows, episodes, audio, Script to audio jobs, and API keys are deleted. Stripe keeps the customer and invoices. An allowlisted admin account is refused with 403. The billing page has the same Delete account action. Success is 204. ## 2026-11-12 — On-demand episodes, topics, and access tokens POST /api/v1/shows/{id}/episodes starts today's episode with the same Free and Pro rules as the website Generate button, including one episode per delivery day and the deleted-day tombstone. It does not debit prepaid credits. DELETE /api/v1/episodes/{id} deletes one owned episode the same way the website Library does. Success is 204 with no body. A missing bearer token is 401. Another account's episode is 404. The row stays deleted, so that day is not generated again, and an allowlisted admin can still reopen that same row. Show and ShowWrite include topics (news, sports, ai, finance, crypto). The website did not store topic ids before migration 034. Handles remain the X accounts. A signed-in access token works on /api/v1 beside a pp_live_ key and is checked with the auth server. Key rotation and credit pack purchase stay on the API key. /api/mcp tool calls stay on the API key. generate_episode and delete_episode are the MCP tools for those routes. ## 2026-10-23 — Signup from another IP, English default Shipped in #80. POST /api/v1/agent-accounts accepts a solved challenge from a different IP than the challenge request. The challenge stays single-use and short-lived. A changed caller IP is not an error. Failed proofs use proof_of_work_expired, proof_of_work_used, or proof_of_work_failed. Signup caps still use signup_rate_limited. Challenge requests and signup attempts use separate per-IP windows. output_language on Script to audio estimate and create defaults to en when the field is omitted or blank. A code that is sent is still validated. ## 2026-10-23 — Listener audio delete Shipped in #79. The website can delete the listener's episode audio and Script to audio. /api/v1 has no delete route. After an episode is deleted, GET /api/v1/episodes and GET /api/v1/episodes/{id} can return status deleted with the script cleared, and audio_url is null. GET /api/v1/episodes/{id}/audio then returns 409 because the episode is not ready. A deleted Script to audio job stays on GET /api/v1/script-audio/{id} with status deleted, an empty title, and an empty script preview. GET /api/v1/script-audio omits it once storage deletion has finished. GET /api/v1/script-audio/{id}/download returns 404 with the message that the audio was deleted. ## 2026-10-22 — Agent accounts Shipped in #68. An agent can open its own account with POST /api/v1/agent-accounts/challenge and POST /api/v1/agent-accounts. The challenge is proof of work. The new key is shown once. POST /api/v1/agent-accounts/verify-email, POST /api/v1/agent-accounts/claim-link, GET /api/v1/credits, POST /api/v1/credits/checkout, POST /api/v1/credits/transfers, and POST /api/v1/keys/rotate shipped in the same change. Trust tiers gate scopes and limits. GET /api/v1 lists Nora, Leo, Kristine, Ken, and Marko. ## 2026-10-22 — Public API and credit packs Shipped in #66. /api/v1 launched with bearer API keys. Signed-in users create those keys at [https://postpodai.com/settings/api](https://postpodai.com/settings/api). The key is shown once and stored as a hash. The first routes were GET /api/v1, GET /api/v1/account/me, show list, create, and update, episode list, episode read, and episode audio, plus Script to audio estimate, create, list, read, and download. Creating a job debits prepaid credits. Packs are $5, $10, $20, $50, $100 USD, bought on the signed-in billing page by card or by USDC. A low balance returns 402. The OpenAPI document and llms.txt shipped with the API. Read the [developer docs](https://postpodai.com/developers), the [API rate limits](https://postpodai.com/developers/rate-limits), and the [API versioning and deprecation policy](https://postpodai.com/developers/deprecation).