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:

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"}}}'

{ "id": "shw_…", "name": "Acme Weekly", "defaults": { "metadata": { "network": "acme" } }, "archived": false,
  "createdAt": "…", "updatedAt": "…" }

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). 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.

Projects in a show

Give a project its show when you create it:

{ "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.*):

{ "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

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

{
  "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.