# Podsworth API
import { Card, CardGrid } from "@astrojs/starlight/components";
One recording, one to eight tracks. We measure every file, charge credits for what we measure, and deliver
each output with its own link. [Projects →](/guides/projects/)
Upload a file with one PUT, or have us import it from any https URL, Dropbox or Google Drive, and use it in
any project. [Files →](/guides/files/)
Test keys run your whole integration, webhooks included, through a simulator. Nothing is processed and nothing
is charged. [Test mode →](/guides/test-mode/)
Signed events for every status change and every credit grant, retried for three days, plus an events feed to
catch up. [Webhooks →](/guides/webhooks/)
## The basics
- **Base URL:** `https://api.podsworth.com`. Live and test keys use the same host.
- **Authentication:** `Authorization: Bearer pw_test_…` (or `pw_live_…`). Owners and admins create keys on their
account page. See [Authentication](/guides/authentication/).
- **Format:** JSON in and out, camelCase fields, timestamps in UTC (ISO 8601). Errors look like
`{"error": {"code": "…", "message": "…"}}`. See [Errors and limits](/guides/errors-and-limits/).
- **Credits:** one credit is one minute of audio, charged by the second for what we measure. Live projects spend
the account's credits when submitted; failed or cancelled projects get them back. See [Credits](/guides/credits/).
- **For agents:** [llms.txt](/llms.txt), [all guides in one file](/llms-full.txt) and the
[OpenAPI file](/openapi.json).
---
# Authentication
Every request carries an API key:
```http
Authorization: Bearer pw_live_...
```
## Keys
Owners and admins of an account create and revoke keys on its account page (people only: a key can't make keys).
A key's secret is shown once; we keep only a hash, so a lost key can't be recovered. Revoke it and create another.
An account can have 50 active keys.
| Prefix | Mode | What it does |
|---|---|---|
| `pw_live_` | live | Real projects, processed by our studio pipeline and paid with the account's credits. |
| `pw_test_` | test | Simulated projects: validated and priced like live ones, never processed, never charged. See [Test mode](/guides/test-mode/). |
A key sees only its own mode's projects, events and webhook endpoints: live and test never mix.
## Permissions
A key holds some of these permissions, chosen when it's made. It can't have one its creator doesn't have.
| Permission | Allows |
|---|---|
| `account:read` | The account's balance, credit history, purchases, and `credits.*` events. |
| `projects:read` | Reading projects and downloading their outputs; the events feed. |
| `projects:write` | Creating projects, uploading, submitting test projects, cancelling, deleting files. |
| `credits:spend` | Submitting live projects (they spend credits). Live keys only. |
| `billing:purchase` | Buying credits with the account's saved card. Live keys only. |
| `webhooks:manage` | Webhook endpoints and their deliveries. |
| `shows:manage` | Adding, renaming and archiving the account's [shows](/guides/shows/). |
| `destinations:manage` | Adding, changing and removing the account's [destinations](/guides/delivery/). |
A request that needs a permission the key doesn't have gets `403` with code `missing_scope`. A test key asking to
spend or buy gets `403` `test_mode`. A key can also be limited to one of a network's shows: see
[Shows and usage](/guides/shows/#keys-and-apps-limited-to-a-show).
## Keys follow the person who made them
A key never does more than its creator can do **now**. If the creator's role on a team changes, the key loses what
the new role can't do; if they leave the team or their user is disabled, the key stops working (`401`). Keys for a
long-running integration are best made by an owner.
## Checking a key
```bash
curl https://api.podsworth.com/v1/me -H "Authorization: Bearer $PODSWORTH_KEY"
```
```json
{ "accountId": "acc_…", "actorType": "api_key", "actorId": "key_…", "mode": "test", "scopes": ["projects:read", "projects:write"] }
```
`scopes` are the permissions the key has right now.
---
# Quickstart
This walks through one project with a **test key**: everything behaves like a live project (statuses, webhooks,
the delivery) except that nothing is processed and nothing is charged. Switch to a live key when you're ready.
## 1. Create a test key
Sign in at [app.podsworth.com](https://app.podsworth.com), open your account page, and under **API keys** create a
key in **Test** mode with these permissions: read projects, create and upload projects. Copy the secret: it's shown
once.
```bash
export PODSWORTH_KEY=pw_test_...
```
## 2. Create the project
```bash
curl https://api.podsworth.com/v1/projects \
-H "Authorization: Bearer $PODSWORTH_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Episode 12", "files": [{"fileName": "episode-12.wav"}], "submit": true}'
```
`submit: true` means it starts by itself as soon as its file is in. The file comes back with an `uploadUrl`:
```json
{
"id": "prj_9f2c41d0b8e64a7c9a11",
"status": "draft",
"mode": "test",
"files": [
{
"id": "file_8c1d4f0e2b7a49d1a3f0",
"fileName": "episode-12.wav",
"status": "awaiting_upload",
"uploadUrl": "https://…s3.us-east-2.amazonaws.com/uploads/…?X-Amz-Signature=…"
}
]
}
```
## 3. Upload the file
PUT the file to its `uploadUrl`. The file is the whole request body: no form, no other headers, and no
`Authorization` either (the URL is signed, and works for three hours). The bytes go straight to our storage, so a
large file never passes through the API.
```bash
curl -T episode-12.wav ""
```
We check the file as soon as it lands (it's measured, and must be audio or video we can read), and the project
moves on: `validating`, then `queued`. If something's wrong it's `rejected` instead, with a reason you can fix
before submitting again ([Projects](/guides/projects/#rejections)).
## 4. Follow it and download the result
Poll `GET /v1/projects/{id}` (every 10 seconds or so), or add a [webhook](/guides/webhooks/) and wait for
`project.completed`. A test project takes about a minute.
```bash
curl https://api.podsworth.com/v1/projects/prj_9f2c41d0b8e64a7c9a11 \
-H "Authorization: Bearer $PODSWORTH_KEY"
```
When it's `completed`, `downloadUrl` is the whole delivery as a zip, `outputs` lists each file with its own link,
and `manifestUrl` describes them. Links last an hour: fetch the project again for fresh ones.
## The same in Python
```python
import os
import time
import requests
API = "https://api.podsworth.com"
HEADERS = {"Authorization": f"Bearer {os.environ['PODSWORTH_KEY']}"}
project = requests.post(f"{API}/v1/projects", headers=HEADERS, json={
"name": "Episode 12", "files": [{"fileName": "episode-12.wav"}], "submit": True}).json()
with open("episode-12.wav", "rb") as f:
requests.put(project["files"][0]["uploadUrl"], data=f).raise_for_status()
while project["status"] not in ("completed", "failed", "rejected", "cancelled"):
time.sleep(10)
project = requests.get(f"{API}/v1/projects/{project['id']}", headers=HEADERS).json()
print(project["status"], project["downloadUrl"] or project["rejection"] or project["failure"])
```
## The same in TypeScript
Node 20 or later (built-in `fetch`):
```ts
import { readFile } from "node:fs/promises";
const API = "https://api.podsworth.com";
const headers = { Authorization: `Bearer ${process.env.PODSWORTH_KEY}`, "Content-Type": "application/json" };
let project = await (await fetch(`${API}/v1/projects`, {
method: "POST", headers,
body: JSON.stringify({ name: "Episode 12", files: [{ fileName: "episode-12.wav" }], submit: true }),
})).json();
const put = await fetch(project.files[0].uploadUrl, { method: "PUT", body: await readFile("episode-12.wav") });
if (!put.ok) throw new Error(`upload failed: ${put.status}`);
while (!["completed", "failed", "rejected", "cancelled"].includes(project.status)) {
await new Promise((r) => setTimeout(r, 10_000));
project = await (await fetch(`${API}/v1/projects/${project.id}`, { headers })).json();
}
console.log(project.status, project.downloadUrl ?? project.rejection ?? project.failure);
```
## Next
- [Files](/guides/files/): upload first and decide later, imports from links, Dropbox and Google Drive.
- [Projects](/guides/projects/): statuses, multi-track projects, changing a project, processing it again.
- [Webhooks](/guides/webhooks/): stop polling.
- [Test mode](/guides/test-mode/): force a failure to test your error handling.
---
# Projects
A project is one recording: one file, or two to eight tracks of the same recording (host, guest, …) that are
processed together. You make it of [files](/guides/files/), change it as much as you like while it's a draft, submit
it, and follow it to a delivery.
## Creating a project
```http
POST /v1/projects
```
```json
{
"name": "Episode 12",
"clientRef": "ep-12",
"metadata": { "show": "Acme Weekly" },
"settings": { "mergeOutput": false },
"files": ["file_8c1d4f0e2b7a49d1a3f0", { "fileName": "guest.wav" }],
"submit": true
}
```
| Field | |
|---|---|
| `files` | The project's files in track order. Each is a file's `id` (one you already made, uploaded or used before), or a new file: `{"fileName": "guest.wav"}` to upload, which comes back with its `uploadUrl`, or `{"fileName", "source"}` to import (see [Files](/guides/files/)). 1 file: processed alone. 2–8: tracks of one recording. Video files (MP4, AVI, …) can't be grouped. May be empty while it's a draft. |
| `submit` | Submit it too: at once if its files are ready, otherwise as soon as they are. |
| `name` | Optional; names the delivery's zip and folder. |
| `clientRef` | Your own id, unique within the account. Filter by it: `GET /v1/projects?clientRef=ep-12`. |
| `metadata` | Up to 20 string keys and values, returned as given. |
| `show` | Optional: one of the account's [shows](/guides/shows/). The project starts with the show's defaults. |
| `keep` | Optional: [keep its files](/guides/keep/) past 30 days. Unsaid: the show's default, else the account's. |
| `deliveries` | Optional: destination ids its files are sent to when it completes ([Drive and Dropbox](/guides/delivery/)). Unsaid: the show's. |
| `settings.mergeOutput` | Two-track projects only: one merged file instead of two. |
While every file is ready, the draft's `creditsSeconds` already says what it will cost.
## Statuses
| Status | Meaning |
|---|---|
| `draft` | Created. Its files, settings and name can change. Submit it when its files are in (or before: it waits). |
| `validating` | Submitted, and waiting for its files to arrive (or be checked). |
| `rejected` | Refused at validation; `rejection` says why. Change it and submit again. |
| `queued` | Charged and waiting for the studio. `estimatedCompletionAt` estimates when it'll be done. |
| `processing` | Being processed; `progress` says the step and roughly how far along. |
| `completed` | Done: download the outputs. |
| `failed` | We couldn't process it after retrying; its credits were refunded. |
| `stopped` | Held by our team (rare). It's queued again or cancelled. |
| `cancelled` | Cancelled before processing; its credits were refunded. |
`POST /v1/projects/{id}/submit` answers with the outcome when it can: if every file is already checked, the project
it returns is `queued` or `rejected`. Otherwise it's `validating` until the files are in (up to 24 hours), then
`queued` or `rejected`. Either way the outcome is the project's `status` and `rejection`, and every change is also a
[webhook event](/guides/webhooks/). A project can go back to `queued` (and `processing`) when we retry it.
### Rejections
| `rejection.code` | Fix |
|---|---|
| `upload_missing` | A file didn't arrive within 24 hours. Upload it and submit again. |
| `unreadable_file` | We couldn't read a file as audio or video. Replace it with a working file and submit again. |
| `file_too_large` | Test mode only: a file is over 500 MB. Replace it with a smaller one. |
| `import_failed` | An import couldn't be downloaded; the file's `error.message` says why. Replace it with a working link. |
| `file_expired` | A file was deleted, or is more than 30 days old. Upload it again and put the new file in the project. |
| `insufficient_credits` | The account doesn't have enough credits. Buy more (the message names a bundle that covers it) and submit again. |
| `measurement_unavailable` | We couldn't check a file just now. Submit again in a minute. |
| `test_limit_reached` | Test mode only: today's test limits are used up. |
| `spend_cap_reached`, `access_revoked` | An [AI assistant](/guides/mcp/) submitted it over its monthly cap, or after it was disconnected. |
## Changing a project
```http
PATCH /v1/projects/{id}
```
```json
{ "files": ["file_8c1d4f0e2b7a49d1a3f0", { "fileName": "guest-take2.wav" }], "settings": { "mergeOutput": true } }
```
Send only what changes. `files` is the whole list, in track order: it replaces the project's (the files taken out
stay yours, to use elsewhere or delete).
| Status | `name`, `metadata`, `clientRef` | `files`, `settings`, `show`, `testOutcome` |
|---|---|---|
| `draft`, `rejected` | yes | yes |
| anything else | yes | no: `409` `invalid_transition` |
Once a project is submitted, what it processes doesn't change. While it's `queued` you can
[cancel it](#cancelling) (its credits come back); to process it again, with the same or other settings and files,
copy it. `name` names the outputs, so renaming a project once processing has started doesn't rename files already
made. `keep` and destinations have their own calls: `POST /v1/projects/{id}/keep` and
`POST /v1/projects/{id}/deliveries`.
## Processing again
```http
POST /v1/projects/{id}/copy
```
```json
{ "settings": { "mergeOutput": true }, "submit": true }
```
A copy is a **new project** with the same files, settings, name, metadata and show, with the changes you send (any
field you'd create a project with, `files` included). It has `copiedFrom`, and the original stays exactly as it was:
its outputs, its charge and its deliveries. It needs no upload while its files last (30 days after they were
uploaded, or for good if the project was [kept](/guides/keep/)); after that, put new files in the copy's `files`
(`409` `file_expired` otherwise). A copy starts without a `clientRef`, and its Keep and destinations follow the
defaults like any new project, unless you send them.
| Situation | What to do | Credits |
|---|---|---|
| A wrong setting, still `queued` | Cancel it, then copy it with the change. | Refunded, then charged for the copy. |
| Other settings or files after it ran | Copy it with the change. | The copy is charged in full; the original's charge stands. |
| It `failed` | Copy it (or write to us). | The failure was refunded; the copy is charged. |
| The result is wrong because of us | Write to support@podsworth.com with the project id. | We reprocess the same project, free. |
## What it costs
`creditsSeconds` is the project's price in credits (seconds of audio): the measured length of all its tracks, with a
small per-project minimum. Every setting costs the same, and both versions of the outputs are included. A live project's credits are taken when it's validated
and given back if it fails or is cancelled. Each run is charged: a copy costs what a new project would. See
[Credits](/guides/credits/).
## Stereo files with a speaker on each side
Some recorders put each mic on its own side of a stereo file: one person on the left, the other on the right. When a
file is checked we tell: such a file has `twoSpeakers: true`, and a project processes it as **two tracks**, its left
side and its right, cleaned separately and mixed into one file. It's priced as two tracks (twice its length), and a
draft's `creditsSeconds` already counts both. When you submit, the project's `tracks` list them (`channel` 0 and 1, in
the file's place):
```json
"files": [{ "id": "file_9f2c", "fileName": "interview.wav", "channels": 2, "twoSpeakers": true, … }],
"tracks": [
{ "fileId": "file_9f2c", "name": "interview (left).wav", "channel": 0 },
{ "fileId": "file_9f2c", "name": "interview (right).wav", "channel": 1 }
]
```
A file on its own becomes a merged 2-track project named after it. In a project with other files, both tracks join
it and count toward its 8 tracks (over 8: rejected with `too_many_tracks`). A stereo file with the same audio on both
sides, or one speaker on both, is one track and priced once (`twoSpeakers: false`); we process its louder side.
## Following a project
```http
GET /v1/projects/{id}
GET /v1/projects?status=queued&limit=50&cursor=…
```
Lists are newest first, at most 100 per page; pass `nextCursor` as `cursor` for the next page.
- `files`: each file, with its status and length (and `uploadUrl` while it's waiting for its upload).
- `estimatedCompletionAt` (queued and processing): when we expect it done, from the queue ahead of it and the
studio's capacity. An estimate, refreshed on every read; `null` while the studio is offline.
- `progress` (processing): `step` (e.g. "Isolating and enhancing dialogue"), `percent`, and `rate`/`cap` if you
animate a progress bar between polls (move at most `rate` percent per second, never past `cap`).
## Outputs
A `completed` project has:
- `downloadUrl`: the whole delivery as one zip (a folder named after the project).
- `outputs`: each delivered file (`kind`: `audio`, `video` or `transcript`, and its `variant`, below) with its own
`url`, then the zip (`zip`). A live project finished before per-file outputs existed has none (and no manifest):
use `downloadUrl`.
- `manifestUrl`: `manifest.json`, describing the outputs (with the same `variant`), the inputs they came from and
the settings.
Every link lasts an hour; read the project again for fresh ones.
Every project comes back in two versions, at no extra cost:
| Ending | `variant` | What it is |
|---|---|---|
| `_pw_vs` | `vs` | The cleaned audio, its length kept so it lines up with the recording: use it under a video. A video file comes back as video with this audio in it. |
| `_pw_ae` | `ae` | The audio edit: the same cleanup with filler words ("um", "uh"), long pauses, coughs and music cut out. It's shorter than the recording, so it's always audio (`.wav`), even for a video. |
A one-file project delivers `_pw_vs.` and `_pw_ae.wav`; a multi-track project delivers each track
(or one merged file) in both versions. Each version has its own transcript, timed to its own audio, named after the
project like its zip: `_pw_vs_transcript.txt` and `_pw_ae_transcript.txt` (a project
without a name uses its first file's). In a multi-track transcript each speaker is their track: `Track 1` is the
project's first file, `Track 2` its second, and so on. The zip and the manifest have no `variant` (`null`).
If the audio edit can't be made for a project, it's delivered with the `_pw_vs` files alone (and their transcript);
we're alerted and follow up.
## Cancelling
`POST /v1/projects/{id}/cancel`: before processing starts (`draft`, `validating`, `rejected`, `queued`). Charged
credits come back.
## Deleting
- `DELETE /v1/projects/{id}/outputs`: deletes the project's outputs (and their kept copies) from storage now. The
project and its usage stay.
- `DELETE /v1/files/{id}`: deletes one of its files ([Files](/guides/files/#listing-and-deleting)).
Everything is deleted after 30 days anyway, unless it's kept.
---
# Files
A **file** is one of your inputs: a recording you uploaded, or one we imported for you. Projects are made of files.
You can make a file on its own (`POST /v1/files`) and use it in a project later, or make it inline when you create
the project (`files: [{"fileName": "host.wav"}]`): it's the same thing either way.
## Uploading
```bash
curl https://api.podsworth.com/v1/files \
-H "Authorization: Bearer $PODSWORTH_KEY" -H "Content-Type: application/json" \
-d '{"fileName": "host.wav"}'
```
```json
{
"id": "file_8c1d4f0e2b7a49d1a3f0",
"fileName": "host.wav",
"status": "awaiting_upload",
"uploadUrl": "https://…s3.us-east-2.amazonaws.com/uploads/…?X-Amz-Signature=…",
"uploadExpiresAt": "2026-10-07T18:02:11Z"
}
```
PUT the file's bytes to `uploadUrl`, as the whole request body:
```bash
curl -T host.wav ""
```
```python
with open("host.wav", "rb") as f:
requests.put(file["uploadUrl"], data=f).raise_for_status()
```
```ts
await fetch(file.uploadUrl, { method: "PUT", body: await readFile("host.wav") });
```
- **Why a separate URL:** the bytes go straight to our storage instead of through the API, so files up to 5 GB
upload as fast as your connection allows. The URL is signed: it needs no `Authorization` header (or any other
header), and works for three hours. Read the file again for a new one.
- **From a browser:** the upload URL accepts a `PUT` from any origin, so your own web app can upload directly
(`fetch` or `XMLHttpRequest`, which reports progress).
- **Its answers come from storage,** not from our API: `200` when it's in, and an XML error otherwise. A `403` with
`Request has expired` means the URL is too old: read the file for a fresh one and PUT again.
- **Limits:** 5 GB per file (500 MB in test mode); at most 100 files waiting for their upload per account.
Accepted: WAV, MP3, M4A, MP4, AVI, FLAC, OGG, AAC and a few more; we read the file itself, not its name.
## Checking
As soon as a file lands we check it: we measure it, and it has to be audio or video we can read. Then it's `ready`,
with its length, or `failed`, with why.
| `status` | |
|---|---|
| `awaiting_upload` | Made; PUT it to `uploadUrl`. |
| `importing` | We're fetching it from its link. |
| `checking` | It's in; we're measuring it (a few seconds). |
| `ready` | `durationSeconds`, `channels`, `sampleRate` and `sizeBytes` are filled in, and for a stereo file `twoSpeakers` (a different speaker on each side: two tracks in a project, see [Projects](/guides/projects/#stereo-files-with-a-speaker-on-each-side)). Usable in projects. |
| `failed` | `error.code` (`unreadable_file`, `file_too_large` in test mode, `import_failed`) and `error.message`. |
| `expired` | Deleted 30 days after it was checked. |
| `deleted` | You deleted it. |
We notice an upload when you next read the file or a project that has it, or straight away if a submitted project is
waiting for it, so you never need to tell us you're done. A file that's in can't change: PUTting to its old URL
afterwards changes nothing we read or process. To use a different recording, make a new file.
A project of ready files shows its price (`creditsSeconds`) before you submit it. `file.ready` and `file.failed`
[webhooks](/guides/webhooks/) tell you when a file is checked.
## Imports
We fetch the file for you. Imports start as soon as the file is made (`status: "importing"`, no `uploadUrl`), and
it's checked like an upload once it's in. A project can be submitted before its imports finish: it waits for them.
| `source` | |
|---|---|
| `{"type": "url", "url": "https://…"}` | Any public https file, e.g. a signed link from your own storage. |
| `{"type": "dropbox", "url": "https://www.dropbox.com/…"}` | A Dropbox share link. |
| `{"type": "googleDrive", "fileId": "…", "accessToken": "…"}` | A Google Drive file, with an OAuth access token that can read it (the `drive.file` scope covers files the user picked). We use the token once and don't keep it. |
```json
{ "fileName": "host.wav", "source": { "type": "url", "url": "https://files.example.com/ep12/host.wav?sig=…" } }
```
Rules for imports:
- https only, and the host must resolve to a public address. We follow up to five redirects, checking each one.
- Dropbox imports stay on Dropbox's hosts and Drive imports on Google's.
- Up to 5 GB per file (500 MB in test mode), and an hour per download.
- At most 24 files importing at once per account (`429` `import_limit`).
When an import fails because of its link (a 4xx answer, too large, a private address), the file is `failed` with
`import_failed` and the reason in `error.message`. Put a new file with a working link in the project
([changing a project](/guides/projects/#changing-a-project)).
## Using a file again
A file isn't tied to one project: put its `id` in any project of the same account and mode, including a copy made to
[process a project again](/guides/projects/#processing-again), with no new upload. Files belong to the key's mode
(live and test never see each other's), and a show's key sees only the files it made.
```json
{ "name": "Episode 12 (merged)", "files": ["file_8c1d4f0e2b7a49d1a3f0", "file_93ab07c2d4e14f5a8b61"] }
```
## Listing and deleting
```http
GET /v1/files?status=ready&limit=50&cursor=…
GET /v1/files/{id}
DELETE /v1/files/{id}
```
Lists are newest first, at most 100 per page; pass `nextCursor` as `cursor` for the next page.
Files are deleted 30 days after they're checked (`expiresAt`), unless a [kept](/guides/keep/) project uses them:
then they're kept too, and `expiresAt` is `null`. `DELETE /v1/files/{id}` deletes one now, kept copy included. It's
refused with `409` `file_in_use` while a submitted project that hasn't finished uses it.
---
# Keeping files
We delete a project's files 30 days after it's completed. **Keep** holds on to them for good, for a one-time fee in
credits: its outputs (the zip, each output file and the manifest) and the [files](/guides/files/) it was made from,
so you can [process it again](/guides/projects/#processing-again) at any time. The fee is a share of what the project cost: 10%, at least
1 minute (`GET /v1/keep-settings` says the current numbers). Test projects are kept for free.
## Asking for Keep
When you create the project:
```json
{ "keep": true, "files": [{ "fileName": "host.wav" }] }
```
Or later, while its files still exist:
```http
POST /v1/projects/{id}/keep (projects:write; live keys also need credits:spend)
```
- A project that isn't completed yet is kept when it completes, and the fee is charged then.
- A completed project is kept at once. Without enough credits for the fee you get `402` `insufficient_credits`,
with the shortfall in `error.details`. More than 30 days after completion its files are gone (`409` `files_gone`).
- The fee is charged once. Asking again does nothing, and a project our team reprocesses stays kept at no extra cost.
The project's `keep` says where it stands:
```json
"keep": { "requested": true, "keptAt": "2026-10-06T18:40:12Z", "inputsKeptAt": "2026-10-06T18:40:12Z",
"feeSeconds": 180, "error": null }
```
`feeSeconds` is what was charged, or what will be once the project is priced (at submit). If keeping fails at
completion, `error` says why: not enough credits, files gone, or the app that asked was disconnected or is over its
monthly cap. A `project.keep_failed` event goes out, and asking again retries. A `project.kept` event follows each
project that's kept.
Kept files are downloaded the same way as any other output, through the project's links. A kept project's input
files stop expiring (their `expiresAt` is `null`), and `inputsKeptAt` says when they were kept; it stays `null` if
they were already gone when the project was kept (its outputs are kept all the same). Deleting a project's outputs
(`DELETE /v1/projects/{id}/outputs`) deletes their kept copies too; deleting a file (`DELETE /v1/files/{id}`) deletes
its kept copy.
## Defaults
Leave `keep` out and the project follows its show, then the account:
- a show's `defaults.keep` (`true` or `false`) applies to its projects ([Shows and usage](/guides/shows/));
- the account's default, `GET /v1/keep-settings` (`defaultKeep`), is set by owners and admins on the account page.
## In the ledger and usage
Keep's fee appears in `GET /v1/ledger` as a `keep_fee` line with the project's id. `GET /v1/usage` counts it with the
project's own credits.
---
# Sending to Drive and Dropbox
A finished project's files can go straight into a Google Drive or Dropbox folder: each audio file, video and
transcript, in a folder named after the project and the day it finished, under the show's name for a show's project
("Podcasts › Acme Weekly › Episode 12 (2026-10-06)"). The zip and the email still come as always.
## Connections and destinations
A **connection** is a Google Drive or Dropbox login, connected by an owner or admin in account settings (it needs a
browser). A **destination** is a connection plus a folder.
```http
GET /v1/connections (projects:read) the logins; never their credentials
GET /v1/destinations (projects:read)
POST /v1/destinations (destinations:manage) {"connectionId", "name", "target"}
GET /v1/destinations/{id} (projects:read)
PATCH /v1/destinations/{id} (destinations:manage) {"name"}, {"target"}
DELETE /v1/destinations/{id} (destinations:manage) removes it; deliveries keep their record
```
`target` is the folder: `{"path": "/Podcasts"}` on Dropbox, `{"folderId": "…", "path": "Podcasts"}` on Drive (the
folder chosen in Google's picker); anything else is `400` `invalid_target`. A name is 1 to 200 characters. Up to 100
destinations per account (`409` `destination_limit`); a connection that isn't the account's, or was removed, is `400`
`unknown_connection`.
A connection whose login stopped working shows `"status": "needs_reconnect"`: reconnect it in account settings, and
deliveries waiting on it go through.
A connection belongs to the account, not to the person who made it. When that person leaves the team, it keeps
working (files still go to its folders) and shows `"connectedByFormerMember": true`, and the account's owners get an
email listing the logins they connected. If a login is that person's own, disconnect it and connect one of the
team's; connecting the same login again makes it the reconnecting person's.
## Sending a project
Name the destinations when you create the project, up to 5:
```json
{ "deliveries": ["dst_…"], "files": [{ "fileName": "host.wav" }] }
```
Leave `deliveries` out and a show's project gets the show's default destinations (`defaults.delivery`, see
[Shows and usage](/guides/shows/)). Files are sent when the project completes.
To send a finished project somewhere (again), while its files exist:
```http
POST /v1/projects/{id}/deliveries (projects:write) {"destinations": ["dst_…"]}
```
A key limited to a show can only use its show's default destinations (`403` `show_limited`). More than 5 waiting
at once is `400` `too_many_destinations`; a destination that isn't the account's is `400` `unknown_destination`, and
one whose connection was removed is `400` `connection_removed`.
## Statuses and retries
The project's `deliveries` lists each one: `waiting`, `sending`, `delivered` (with `externalUrl`, the folder),
`failed` (with `error`) or `cancelled`. The project itself stays `completed` whatever happens to its deliveries.
- A busy or unreachable service is tried again, from a minute apart up to an hour, for 24 hours.
- A login that stopped working marks the connection `needs_reconnect` and keeps trying, so reconnecting finishes it.
- A folder that's gone, or an account out of space, fails it with the reason.
- Files that are gone (deleted, or past the 30 days without [Keep](/guides/keep/)) fail it: `files_expired`.
A failed delivery's `error.code`:
| Code | |
|---|---|
| `folder_missing` | The folder was deleted or moved. |
| `folder_forbidden` | The login can't write to the folder any more. |
| `storage_full` | The Drive or Dropbox account is out of space. |
| `files_expired` | The project's files are gone. |
| `timed_out` | 24 hours of tries didn't get the files there. |
| `connection_removed` | The connection was removed from the account. |
| `destination_archived` | The destination was removed. |
| `provider_error` | Google or Dropbox refused the files for another reason (`error.message` says what). |
`POST /v1/deliveries/{id}/retry` tries a failed one again, into the folder it made (`409` `already_retried` if it's
already being tried again).
Failures are also emailed to the account's owners and admins, at most once an hour, listing each one with its id.
Anyone can turn these emails off for themselves with `deliveryAlerts` in `PATCH /v1/email-preferences`. A test
project's failures aren't emailed.
## Events
- `delivery.succeeded` and `delivery.failed`, with the delivery as `data.object`.
- `connection.needs_reconnect` when a login stops working.
- `project.completed` carries `outputs`: each file with a `url` that works as long as the files do (30 days, or for
good when kept). Every webhook attempt checks the files first: if they're gone, `filesAvailable` is `false` and
there are no links.
## Test mode
A test project's deliveries go through every status without reaching Google or Dropbox.
---
# Test mode
Projects created with a test key (`pw_test_…`) go through every step a live project does, with real statuses, real
signed webhooks to your test endpoints, and a real delivery, but nothing reaches our studio and nothing is charged.
## What happens
1. Validation is real: uploads and imports are checked and measured, and `creditsSeconds` shows what the project
would cost live. No credits move.
2. `queued` for about 5 seconds, then `processing` for 30–60 seconds (fixed per project), with `progress` moving
through the same steps as a live project.
3. `completed`. The delivery is **your own files**, laid out and named exactly like a live delivery (each output
file in both versions, a zip with a folder, `manifest.json`), plus placeholder transcripts.
## Forcing an outcome
Create the project with `testOutcome` (test keys only; a live key gets `400` `test_outcome_live`):
| `testOutcome` | |
|---|---|
| `completed` | The default. |
| `failed` | Fails 60 % of the way through processing, with `failure.code: "processing_failed"`. |
| `slow` | Takes about 10 minutes, to test long waits and `estimatedCompletionAt`. |
```json
{ "name": "Failure drill", "testOutcome": "failed", "files": [{ "fileName": "ep.wav" }] }
```
## Limits
Test mode protects the studio's capacity:
- files up to 500 MB;
- 50 test projects created per account in any 24 hours (`429` `test_limit_reached`);
- 5 GB of files submitted per account in any 24 hours (a `rejected` project with `test_limit_reached`).
Test projects, events and webhook endpoints are separate from live ones: a test key never sees live data, and a
live key never sees test data.
---
# Webhooks
Instead of polling, add an endpoint and we POST each of your account's events to it as it happens.
## Adding an endpoint
On your account page under **Webhooks**, or with a key that has `webhooks:manage`:
```bash
curl https://api.podsworth.com/v1/webhook-endpoints \
-H "Authorization: Bearer $PODSWORTH_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.com/podsworth/webhooks", "eventTypes": ["project.completed", "project.failed"]}'
```
The response holds the endpoint and its signing `secret` (`whsec_…`), shown only now. `eventTypes` defaults to
`["*"]`: every type, including ones we add later. An endpoint gets its key's mode: test events only reach test
endpoints. Up to 16 endpoints per mode. The URL must be https on a public address. An endpoint can be limited to
one of a network's shows (`"show": "shw_…"`): see [Shows and usage](/guides/shows/#webhooks-for-a-show).
`GET /v1/webhook-endpoints` lists them; `GET`, `PATCH` (`url`, `eventTypes`, `description`, `enabled`) and `DELETE`
`/v1/webhook-endpoints/{id}` read, change and delete one. Deleting drops the deliveries still waiting.
## Events
| Type | When |
|---|---|
| `project.validating` | The project was submitted. |
| `project.rejected` | Validation refused it (`data.object.rejection`). |
| `project.queued` | It's waiting for the studio (again, after a retry). |
| `project.processing` | Processing started. |
| `project.completed` | Done: `data.object.outputs` has each file's download link while the files exist (`filesAvailable`). |
| `project.failed` | It failed for good (`data.object.failure`); its credits were refunded. |
| `project.stopped` | Our team put it on hold. |
| `project.cancelled` | It was cancelled before processing. |
| `project.kept` | Its files were kept past 30 days, and Keep's fee charged (`data.keepFeeSeconds`). See [Keeping files](/guides/keep/). |
| `project.keep_failed` | Keeping it at completion didn't happen (`data.error`): ask again to retry. |
| `file.ready` | A [file](/guides/files/) was checked: `data.object.durationSeconds` is its length. |
| `file.failed` | A file can't be used (`data.object.error`): unreadable, too large in test mode, or its import failed. |
| `delivery.succeeded` | A project's files reached a [Drive or Dropbox folder](/guides/delivery/). |
| `delivery.failed` | A delivery stopped trying (`data.object.error`). |
| `connection.needs_reconnect` | A Drive or Dropbox login stopped working: reconnect it in account settings. |
| `credits.added` | Credits arrived: a purchase, the trial, a grant, a refund (`data.object.reason`). |
| `credits.low` | The balance dropped below the account's threshold (at most once a day). |
| `subscription.renewed` | A monthly plan renewed: its month is paid and its hours granted (`data.secondsGranted`). |
| `subscription.payment_failed` | A plan's renewal couldn't be charged; Stripe retries, and the plan is `past_due` meanwhile. |
| `subscription.canceled` | A plan ended. Its hours stay usable. |
| `billing.topup_failed` | Auto top-up couldn't buy credits: `data.object.reason` is `declined` (auto top-up pauses) or `monthly_cap`. |
## The payload
```http
POST /podsworth/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Podsworth-Webhooks/1.0 (+https://docs.podsworth.com/guides/webhooks/)
Podsworth-Event-Id: evt_3b1f…
Podsworth-Event-Type: project.completed
Podsworth-Signature: t=1791245100,v1=5f2b…
```
```json
{
"id": "evt_3b1f…",
"object": "event",
"type": "project.completed",
"mode": "live",
"createdAt": "2026-10-06T14:05:00Z",
"data": {
"previousStatus": "processing",
"object": {
"object": "project", "id": "prj_9f2c…", "status": "completed", "mode": "live", "name": "Episode 12",
"clientRef": "ep-12", "metadata": { "show": "Acme Weekly" }, "creditsSeconds": 2512,
"rejection": null, "failure": null,
"createdAt": "…", "queuedAt": "…", "startedAt": "…", "completedAt": "2026-10-06T14:05:00Z"
}
}
}
```
`data.object` is the project as it was at that moment. A `project.completed` also has `outputs`, each file with a
download `url` that works as long as the files do (30 days, or for good when kept), checked on every attempt: once
the files are gone, `filesAvailable` is `false` and there are no links. `GET /v1/projects/{id}` always has fresh ones.
### The other events
Every event has the same envelope; `data.object` (`object` says which kind) and a few fields beside it change:
| Type | `data.object` | Beside it |
|---|---|---|
| `project.kept`, `project.keep_failed` | the project | `keepFeeSeconds`; `error` (`code`, `message`) |
| `file.*` | the file: `id`, `fileName`, `status`, `durationSeconds`, `sizeBytes`, `error`, `expiresAt`, `show` | |
| `delivery.*` | the delivery: `id`, `kind` (`google_drive` or `dropbox`), `status`, `projectId`, `destination` (`id`, `name`), `externalUrl`, `error`, `attempts` | |
| `connection.needs_reconnect` | the connection: `id`, `provider`, `label`, `externalAccount`, `status`, `lastError` | |
| `credits.added` | `seconds`, `reason` (`purchase`, `plan_grant`, `trial`, `admin_grant`, `refund`), `bucket`, and the `projectId`, `orderId` or `purchaseId` behind it | |
| `credits.low` | `balanceSeconds`, `thresholdSeconds` | |
| `subscription.*` | the plan: `id`, `status`, `planId`, `seconds`, `amountCents`, `currentPeriodEnd`, `cancelAtPeriodEnd` | `secondsGranted` (renewed); `invoiceId` (payment failed) |
| `billing.topup_failed` | `reason`: `declined` (with `message` and `bundleId`) or `monthly_cap` (with `monthlyCap` and `balanceSeconds`) | |
Events about the whole account (`credits.*`, `subscription.*`, `billing.*`, `connection.*`) are live: they reach live
endpoints, never test ones, and never an endpoint limited to a show. Paying by invoice has no events of its own: an
invoice's hours arrive as `credits.added` (`reason: "purchase"`) when it's sent, and its payment shows in the
purchase's `status` ([Credits](/guides/credits/#paying-by-invoice)).
## Verifying the signature
`Podsworth-Signature` is `t=,v1=." with your secret>`. Compute it
over the **raw** request body (before parsing JSON), compare in constant time, and reject a `t` more than five
minutes from now.
```python
import hashlib
import hmac
import time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(item.split("=", 1) for item in header.split(","))
timestamp = int(parts.get("t", "0"))
if abs(time.time() - timestamp) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
```
```ts
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret: string, header: string, body: string | Buffer, toleranceSeconds = 300): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const t = Number(parts.t);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${t}.`).update(body).digest("hex");
const given = String(parts.v1 ?? "");
return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```
## Answering
Answer with any `2xx` within 10 seconds; do slow work afterwards. Anything else (another status, a redirect, a
timeout) is a failure and we try again: after 1 and 5 minutes, 30 minutes, 2, 5 and 10 hours, then about every
10–12 hours until the event is three days old. If an endpoint has had no success for three days we turn it off and
email the account's owners and admins; fix it and turn it back on from the account page (or `PATCH` with
`"enabled": true`).
Events can arrive more than once and out of order. Use the event `id` to skip ones you've handled, and the
project's own status (or `GET` it) rather than the order events arrived in.
## Testing an endpoint
`POST /v1/webhook-endpoints/{id}/test` sends a `ping` event right away (not retried), and
`GET /v1/webhook-endpoints/{id}/deliveries` shows every delivery's status, attempts, and the start of what your
endpoint answered. Retry one with `POST …/deliveries/{deliveryId}/retry`. Test keys' projects make realistic test
events: see [Test mode](/guides/test-mode/).
## Rolling the secret
`POST /v1/webhook-endpoints/{id}/rotate-secret` returns a new secret, used from the next delivery on. A replayed
request (with the same `Idempotency-Key`) answers `"secret": null`: roll it again if you missed it.
## The events feed
`GET /v1/events` lists the same events, newest first, kept 30 days: catch up after an outage, or poll instead of
receiving webhooks. Filter with `type=project.completed` or `type=project.*`; page with `cursor`. `credits.*`,
`subscription.*` and `billing.*` events need `account:read`.
---
# Errors and limits
## Errors
Errors have an HTTP status and a body with a stable `code` to branch on and a `message` to show a person:
```json
{ "error": { "code": "insufficient_credits", "message": "This project needs 41 min of credits and the account has 12 min." } }
```
| Status | Means | Some codes |
|---|---|---|
| `400` | The request is wrong. `validation_error` lists the fields in `details`. | `validation_error`, `invalid_file_count`, `video_in_project`, `invalid_merge`, `invalid_source`, `duplicate_file`, `invalid_url`, `invalid_cursor`, `unknown_show`, `show_archived`, `unknown_destination`, `too_many_destinations`, `invalid_target`, `unknown_bundle`, `invalid_threshold`, `invalid_cap` |
| `401` | No key, an invalid or revoked key, or its creator left the account. | |
| `402` | Payment needed: not enough credits for Keep's fee, or the card was declined. | `insufficient_credits`, `card_declined` |
| `403` | The key can't do this. | `missing_scope`, `test_mode`, `account_suspended`, `show_limited`, `invoice_billing_off`, `user_only`, `not_for_apps` |
| `404` | Not found, or not yours (another account's, the other mode's, or another show's for a key limited to one). | `not_found`, `file_not_found` |
| `409` | It conflicts with the current state. | `invalid_transition`, `duplicate_client_ref`, `file_expired`, `file_failed`, `file_in_use`, `idempotency_key_reused`, `endpoint_limit`, `duplicate_show`, `show_limit`, `destination_limit`, `files_gone`, `no_saved_card`, `invoice_overdue`, `invoice_limit_reached` |
| `413` | The body is over 1 MB. | `payload_too_large` |
| `429` | Too many requests or a limit reached. | `rate_limited`, `test_limit_reached`, `import_limit`, `upload_limit` |
| `5xx` | Our fault. Retry with backoff (safely, with an `Idempotency-Key`). | |
Request bodies take only the fields this reference lists: anything else (a typo, or a field from another shape, such
as `url` where a file's `source` belongs) is `400` `validation_error`, with the field named in `details`, rather
than ignored. The same goes for the keys of a file's `source`.
A project that validation refuses isn't an error response: it's `rejected` with a `rejection.code` (see
[Projects](/guides/projects/#rejections)).
## Rate limits
120 requests a minute per key. Over that you get `429` `rate_limited` with a `Retry-After` header (seconds).
Poll a project every 10 seconds or so, or use [webhooks](/guides/webhooks/).
## Idempotent retries
Send an `Idempotency-Key` header (any unique string up to 255 characters) on a POST to make retrying it safe. Within
24 hours, the same key with the same body returns the first response again, with `Idempotent-Replayed: true`,
instead of acting twice. The same key with a different body is `409` `idempotency_key_reused`; a retry while the
first request is still running is `409` `idempotency_in_progress`. A `5xx` isn't kept, so retrying it runs again.
Keys belong to the API key that sent them.
```bash
curl https://api.podsworth.com/v1/projects \
-H "Authorization: Bearer $PODSWORTH_KEY" -H "Idempotency-Key: ep-12-create" \
-H "Content-Type: application/json" -d '{"files": [{"fileName": "ep12.wav"}]}'
```
## Pagination
Lists (`/v1/projects`, `/v1/events`, deliveries) return the newest first and a `nextCursor`; pass it back as
`cursor` for the next page, until it's `null`. `limit` is 20 by default, at most 100.
---
# Credits
Live projects are paid with the account's **credits**: one credit is one minute of audio, charged by the second for
what we measure in the files (all tracks of a project), with a small per-project minimum. Every processing setting
costs the same. Credits don't expire.
- A live project's credits are taken when it's validated (submitting needs `credits:spend`). Not enough credits:
the project is `rejected` with `insufficient_credits`.
- A project that fails for good, or is cancelled before processing, gets its credits back automatically.
- Each run is charged: a project [copied to process it again](/guides/projects/#processing-again) costs what a new
project would. When a result is wrong because of us, we reprocess it for free: write to support@podsworth.com.
- Test projects show their price in `creditsSeconds` and are never charged.
Buy credits as bundles, or as a monthly plan, on the account page (or
[podsworth.com/pricing](https://podsworth.com/pricing)).
## Monthly plans
A plan adds its hours every month, for a little less than the same bundle. They're spent before any other credits.
Unused plan hours roll over, at most one month's worth: at each renewal anything above a month's hours is dropped
before the new month's are added. Bundle hours are never touched. Change or cancel a plan in **Billing details** on
the account page; changes start at the next renewal, and after a cancellation the hours you have stay usable.
`GET /v1/subscription` (`account:read`) shows the plan, or the last one the account had (`null` if none): its
`planId`, `seconds` and `amountCents` per month, `status`, `live` (`true` while it's the account's plan), and
`currentPeriodEnd` (when it renews, or ends if `cancelAtPeriodEnd`). Subscribing, changing and cancelling happen on
the account page, for signed-in people only: a key or an assistant can read the plan but not change it.
| `status` | |
|---|---|
| `active` | Paid up. |
| `past_due` | A renewal's payment failed and the card is tried again. The new month's hours wait for the payment; the hours already in stay usable. |
| `canceled` | It ended. The hours it added stay usable. |
When a renewal can't be charged, the account's owners and billing members get one email for that renewal, with a link
to pay it (with the same card or another) and when the card will be tried again. A `subscription.payment_failed` event
(`data.invoiceId`) goes out on every failed charge: the renewal's, each retry's, and a first payment that fails in
checkout (that one gets no email: the person is there). Once it's paid, the month's hours are added and
`subscription.renewed` follows.
## Auto top-up
Auto top-up buys a bundle with the saved card whenever the balance drops below a threshold, at most a set number of
times a month (3 by default, up to 20), so an integration never runs dry and a runaway one can't drain a card.
```http
PUT /v1/auto-top-up (billing:purchase)
```
```json
{ "enabled": true, "thresholdSeconds": 7200, "bundleId": "5h", "monthlyCap": 3 }
```
`thresholdSeconds` is between 10 minutes and 100 hours (`invalid_threshold`), `monthlyCap` 1 to 20 (`invalid_cap`).
Turning it on needs a bundle on sale (`invalid_bundle`, `unknown_bundle`) and a saved card, which the account gets
from its first purchase through checkout on the account page (`409` `no_saved_card`). The month runs on US Central
time. People and API keys change auto top-up; a connected assistant can't (`403` `not_for_apps`), since its purchases
have their own monthly cap.
If a charge is declined (or the bank wants 3-D Secure, which nobody is there to answer), auto top-up pauses, the
account's owners and billing members get an email, and a `billing.topup_failed` event goes out. Saving the settings
again turns it back on. `GET /v1/auto-top-up` shows the settings, a pause and its reason, and this month's purchases.
## Paying by invoice
Teams that pay through a finance department can ask us (info@podsworth.com) to be invoiced. On an account set up
for it, a person signed in as an owner or billing member can buy a bundle on a **net-30 invoice** from the account
page: Stripe emails the invoice to the billing address, and the hours are added at once. Pay it within 30 days by
bank transfer (ACH or wire, to the account number on the invoice), ACH debit or card.
- Each account has a limit on what it may owe on invoices at once; an invoice that doesn't fit is refused with
`409` `invoice_limit_reached` (`error.details` has `limitCents` and `owedCents`).
- While an invoice is past due, or one was written off unpaid, no new ones can be sent (`409` `invoice_overdue`).
Buying with a card still works.
- An account that isn't set up for invoices gets `403` `invoice_billing_off`.
- The hours arrive as a `purchase` line in the ledger and a `credits.added` event when the invoice is sent. Paying it
changes the purchase's status, with no event.
- If an invoice is cancelled, or written off unpaid, the hours it added that are still unspent come back out (an
`invoice_void` line in the ledger).
`GET /v1/credits/invoicing` (`billing:purchase`) shows whether the account pays by invoice, its limit, what it owes and
its open invoices with their due dates. In the purchase list and the ledger, an unpaid invoice's purchase has the
status `invoiced` and an `invoiceDueAt`; it becomes `paid` when the payment arrives. Asking for an invoice is for
people on the account page: keys and connected apps buy with the card (below).
## Balance and history
```http
GET /v1/balance (account:read)
GET /v1/ledger (account:read)
```
`GET /v1/balance` answers `totalSeconds` and `buckets` (seconds left in each: plan, promo, purchased). Projects
spend plan hours first, then promotional ones (the trial), then purchased ones.
`GET /v1/ledger` lists every change, newest first, each with its `kind`, `bucket` and `deltaSeconds` (negative when
credits go out):
| `kind` | |
|---|---|
| `purchase` | A bundle, an auto top-up or an invoice's hours (`purchase` has what was paid). |
| `plan_grant` | A plan's month. |
| `rollover_cap` | Plan hours over one month's, dropped at a renewal. |
| `trial` | The free trial. |
| `admin_grant`, `admin_revoke` | Our team added or took back credits (`note` says why). |
| `debit` | A project's or an order's charge. |
| `refund` | A failed or cancelled project's credits back. |
| `keep_fee` | [Keep](/guides/keep/)'s fee. |
| `purchase_refund` | A refunded purchase's unspent hours taken back. |
| `invoice_void` | A cancelled or written-off invoice's unspent hours taken back. |
`GET /v1/usage` adds up what projects used, by day or by show: see [Shows and usage](/guides/shows/#usage).
## Buying from the API
With a **live** key that has `billing:purchase`, `POST /v1/credits/buy` buys a bundle with the account's saved card
(the card used for its last purchase on the account page):
```json
{ "bundleId": "5h" }
```
`status` is `paid` when the credits are in (a `credits.added` event follows), or `pending` when the card's bank
wants 3-D Secure. A person has to complete that in a browser, so buy ahead of need when you automate it, and
watch `credits.low`. A declined card is `402` `card_declined` with the bank's reason; an account with no saved card
yet is `409` `no_saved_card`. `GET /v1/credits/purchases` lists the account's purchases, and
`GET /v1/credits/purchases/{id}` one of them.
---
# Shows and usage
A network can run all its shows from one account: one balance, one team, and each project in its show. Keys,
connected apps and webhook endpoints can be limited to one show, and usage is counted per show, for billing your
shows yourselves. An account with one podcast doesn't need any of this.
## Shows
Owners and admins add shows on the account page under **Shows**, or with a key that has `shows:manage`:
```bash
curl https://api.podsworth.com/v1/shows \
-H "Authorization: Bearer $PODSWORTH_KEY" -H "Content-Type: application/json" \
-d '{"name": "Acme Weekly", "defaults": {"metadata": {"network": "acme"}}}'
```
```json
{ "id": "shw_…", "name": "Acme Weekly", "defaults": { "metadata": { "network": "acme" } }, "archived": false,
"createdAt": "…", "updatedAt": "…" }
```
```http
GET /v1/shows (projects:read) ?archived=true lists the archived ones too
GET /v1/shows/{id} (projects:read)
POST /v1/shows (shows:manage)
PATCH /v1/shows/{id} (shows:manage) {"name"}, {"defaults"}, {"archived": true | false}
```
Names are up to 200 characters and unique among the account's shows (`409` `duplicate_show`), and an account has
up to 200 shows that aren't archived (`409` `show_limit`). **Archiving** takes a show off the lists and stops new
projects in it (`400` `show_archived`); its projects, keys and endpoints keep it, and it can be unarchived. Shows are
shared by live and test.
**Defaults** apply to the show's new projects: `metadata` is added to each project's own (the project's keys win).
`keep` (`true` or `false`) decides whether the show's projects keep their files ([Keeping files](/guides/keep/)).
Changing them doesn't touch existing projects. `PATCH` replaces the whole `defaults` object. `metadata` has the
same limits as a project's (`400` `invalid_metadata`).
`delivery` lists the show's default destinations, `[{"destinationId": "dst_…"}]` (up to 5; one that isn't the
account's is `400` `unknown_destination`): its new projects' files are sent there when they complete, unless the
project names its own. See [Sending to Drive and Dropbox](/guides/delivery/).
## Projects in a show
Give a project its show when you create it:
```json
{ "show": "shw_…", "files": [{ "fileName": "host.wav" }] }
```
The project's `show` holds it, and `GET /v1/projects?show=shw_…` lists one show's projects. On the account page,
someone uploading picks the show at checkout. An unknown show is `400` `unknown_show`.
## Keys and apps limited to a show
When you create a key on the account page, choose a **Show** to limit it to that show. People connecting an
assistant (MCP) can do the same on the consent page. A key or app limited to a show:
- puts every project it creates in its show (asking for another is `403` `show_limited`);
- sees only that show's projects (another show's are `404`) and only their events, in the events feed and on its
webhook endpoints;
- makes webhook endpoints for its show only;
- can't read or change what spans the account (`GET /v1/ledger`, `GET /v1/orders`, the purchases, the plan, auto
top-up and invoicing: `403` `show_limited`) or manage shows.
It can still read the account's balance (with `account:read`), and spend its credits like any key with
`credits:spend`. `GET /v1/me` answers `show` for a key limited to one.
## Webhooks for a show
An endpoint created with a `show` gets only that show's projects' events, and nothing account-wide
(`credits.*`, `subscription.*`):
```json
{ "url": "https://acme.example.com/podsworth", "show": "shw_…" }
```
Each project event's `data.object.show` says which show it's from, for endpoints that get every show's events.
## Usage
```http
GET /v1/usage?from=2026-10-01&to=2026-10-31&groupBy=show (account:read)
GET /v1/usage.csv?from=2026-10-01&to=2026-10-31&groupBy=show
```
```json
{
"from": "2026-10-01", "to": "2026-10-31", "mode": "live", "groupBy": "show",
"total": { "seconds": 54000, "projects": 31 },
"rows": [
{ "show": { "id": "shw_…", "name": "Acme Weekly" }, "seconds": 36000, "projects": 20 },
{ "show": null, "seconds": 18000, "projects": 11 }
]
}
```
- `seconds` are the credits the projects took, refunds taken off, on the day they happened. Store orders paid with
credits count, as well as API projects.
- `groupBy` is `day` (one row per day with usage, `date` in US Central time) or `show` (`show: null` is projects in
no show). Without it, `rows` is empty and `total` has the sum.
- `from` defaults to the first of this month and `to` to today, both included; at most 366 days.
- `show=shw_…` counts one show. A key limited to a show always gets its own show's usage.
- A test key gets what live would have charged for its test projects.
- The `.csv` form has the same rows with minutes, for a spreadsheet.
---
# AI assistants (MCP)
Podsworth is a remote [MCP](https://modelcontextprotocol.io) server. An AI assistant connected to it can check your
balance, estimate a cost, create and submit projects, follow them and fetch the downloads, using the same projects
and credits as the API.
```
https://api.podsworth.com/mcp
```
## Connecting
Add that address to your assistant as a remote MCP server (in Claude: a custom connector). The first time it's used,
the assistant opens Podsworth's sign-in page, then a page where you choose:
- **the account** it acts for, if you're in a team;
- **a show**, for a network's account: limited to one, it only sees and makes that show's projects (see
[Shows and usage](/guides/shows/#keys-and-apps-limited-to-a-show));
- **live or test**: a test connection only sees and makes [test projects](/guides/test-mode/), which are free;
- **what it may do**: it can always see the account's balance and projects. You can also let it **create projects and
spend credits** on them, with a monthly cap in hours, and **buy credits with the account's saved card**, with a
monthly cap in dollars.
The assistant never sees your password. It can never do more than your own role in the account allows, and it stops
working if you leave the account, sign out everywhere or change your password. See and disconnect your connected apps
on your account page.
### Claude Code
```sh
claude mcp add --transport http podsworth https://api.podsworth.com/mcp
```
Then run `/mcp` in Claude Code to sign in. Clients that can't sign in through a browser can use an
[API key](/guides/authentication/) instead:
```sh
claude mcp add --transport http podsworth https://api.podsworth.com/mcp \
--header "Authorization: Bearer pw_test_…"
```
## Tools
| Tool | What it does |
|---|---|
| `get_account` | The balance, live or test, what this connection may do, its caps and how much of them is used, and the bundles on sale. |
| `estimate_cost` | What files of these lengths would cost, and whether the balance covers it. Charges nothing. |
| `create_project` | A draft project (submitted too with `submit`). Files with a `url` (a public https link or a Dropbox share link) start importing at once; the others come back with an upload URL. |
| `update_project` | Changes a draft or rejected project's files, name or merging, e.g. to replace a file that couldn't be read. |
| `get_upload_link` | A page for you to drop your audio files into a project the assistant created, for when the files are on your computer. It works for 24 hours. |
| `submit_project` | Checks the files, charges the credits and queues the project, or rejects it with a reason. |
| `copy_project` | Processes a project again: a new project from the same files, with other settings or files, charged like any project. |
| `get_project` | Status, progress, cost, `estimatedCompletionAt`, why it was rejected or failed. |
| `list_projects` | The account's projects, newest first; one show's with `show`. |
| `list_shows` | The account's shows, to put a project in one with `create_project`'s `show`. |
| `list_destinations` | The account's Drive and Dropbox folders, for `create_project`'s `deliveries` or `send_project`. |
| `send_project` | Sends a project's files to folders: now if it's finished, otherwise when it finishes. |
| `get_downloads` | Links to a completed project's files (valid for an hour). |
| `cancel_project` | Cancels before processing starts; the credits come back. |
| `delete_project_files` | Deletes the processed files, and the uploaded ones no other unfinished project uses, now. |
| `keep_project` | Keeps a project's files past 30 days, for a fee in credits that counts toward the connection's cap. |
| `buy_credits` | Buys a bundle with the saved card, within the monthly cap; without that permission, returns a link for you to buy it. |
## Getting audio in
Assistants in a chat usually can't attach files from your computer to a tool call. Give them a link instead (a public https URL or a Dropbox share link), or tell them the file names: they create the project and give you an **upload page** (`get_upload_link`) where you choose each file, then submit it when you say you're done.
Assistants that can run commands, such as Claude Code, can also upload themselves: each file in `create_project`'s answer has an `uploadUrl`; PUT the file there (`curl -T host.wav ""`), as in the [quickstart](/quickstart/).
## Limits and money
- A project costs what it would through the API; the assistant can't go past the monthly cap you set. A submit over
the cap is rejected with `spend_cap_reached`, and the project waits for you to submit it or connect the assistant
again with a higher cap.
- Buying over the monthly purchase cap is refused with `purchase_cap_reached`. If the bank asks the cardholder to
confirm a purchase, the assistant gets a link for you.
- Plans, auto top-up and invoices are yours to set up on the account page: an assistant can't start a plan
(`user_only`) or change auto top-up (`not_for_apps`), whatever it may buy.
- Requests count toward the same rate limits as an API key: 120 a minute per connection.