# VocalStack API

> VocalStack is a speech API: realtime and file transcription with speaker labels, live translation into many languages, spoken translations (text to speech), and hosted broadcasts that listeners join by link. One API, `/v1`: realtime sessions (stateless, streamed over a WebSocket), transcriptions, broadcasts, recordings and voices, with transcripts and translations streamed to subscribers.

## Guides

One flow per guide, steps first, then complete programs (TypeScript SDK, Python SDK, HTTP + WebSocket):

- [Quickstart](https://api.vocalstack.com/docs/guides/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
- [Transcribe a file](https://api.vocalstack.com/docs/guides/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
- [Transcribe a link](https://api.vocalstack.com/docs/guides/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
- [Stream a microphone](https://api.vocalstack.com/docs/guides/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
- [Stream a file at full speed](https://api.vocalstack.com/docs/guides/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
- [Go live](https://api.vocalstack.com/docs/guides/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
- [Listen](https://api.vocalstack.com/docs/guides/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
- [Live translation and spoken translations](https://api.vocalstack.com/docs/guides/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
- [Errors, retries and limits](https://api.vocalstack.com/docs/guides/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.

## Docs

- [API reference](https://api.vocalstack.com/docs): interactive reference, with a key box to try calls
- [OpenAPI](https://api.vocalstack.com/v1/openapi.json): the whole API in one document (WebSocket frames under `x-websocket`)
- [Every operation in detail](https://api.vocalstack.com/llms-full.txt): parameters, auth mode and scopes
- MCP server: https://api.vocalstack.com/v1/mcp (Streamable HTTP; the same API keys, or OAuth through https://api.vocalstack.com/.well-known/oauth-protected-resource/v1/mcp)
- SDKs: TypeScript (`@vocalstack/sdk`) and Python (`vocalstack`); install commands in the reference's Install section, and https://api.vocalstack.com/sdk/latest

## Authentication

- Send `Authorization: Bearer <token>`. The token is an API key (`vs_key_…`) or a signed-in person's WorkOS access token.
- API keys are for servers; create them in the VocalStack app. A key carries scopes: `read`, `write`, `recordings:publish`, or `*` for all.
- Each operation lists its auth mode (`public`, `optional`, `user`, `key`, `userOrKey`, …) and the key scopes it needs, in the OpenAPI extensions `x-vocalstack-auth` and `x-vocalstack-scopes`. Every operation is open to every plan; a creation point is refused `402 insufficient_credit` when the account's credit is out.
- OAuth protected-resource metadata (RFC 9728): https://api.vocalstack.com/.well-known/oauth-protected-resource

## billing

- `GET /v1/billing`: Get the account's billing. The acting account's plan, rates (dollars an hour of audio), credit balance, whether it runs on in a grace period below zero (`inGrace`), whether a new transcription would start now and what would refuse it (`canStart`, `startBlock`), the billing period and the one before, the monthly credit's use, the counted limits in use, the subscription (next payment, a scheduled interval switch, past due), auto top-up with its last attempt, the low-balance alert, a payment still being processed, the default card, a scheduled rate change, the retention deadline after a downgrade, the plan's limits and whether it has paid.
- `PUT /v1/billing/auto-top-up`: Set auto top-up. Turn auto top-up on (`threshold` and `amount`: any whole-cent values inside the plan list's `autoTopUp.thresholdRange` and `amountRange`; when the balance falls to the threshold, the amount is charged to the saved payment method, at most a few times a day) or off.
- `POST /v1/billing/auto-top-up/retry`: Run auto top-up now. Charge the configured auto top-up amount to the saved payment method now, whatever the balance (after a declined attempt, once the card is fixed).
- `GET /v1/billing/charges`: List the charges. The account's per-recording charges, newest first, with the transcription's name: open while the audio runs (metered every minute), settled once the recording ends, void when waived.
- `POST /v1/billing/checkouts`: Open a checkout. Start a payment at the payment provider: `{kind: "topup", amount}` adds credit (any whole-cent amount inside the plan list's `topUpRange`), `{kind: "subscribe", planId, interval}` starts a subscription (`month` or `year`); `promoCode` adds a code's bonus credit to a top-up or its discount to a subscription's first payment (`404 promo_code_invalid` when it does not apply).
- `GET /v1/billing/checkouts/{id}`: Get a checkout. A checkout's status, for the page the customer comes back to: by its `checkoutId` or the provider's id (`?checkout=` on the return URL).
- `GET /v1/billing/details`: Get the invoice details. The name, email, address and tax id invoices and receipts carry.
- `PUT /v1/billing/details`: Set the invoice details. Save the invoice details; they are written onto the provider's customer and prefill every checkout.
- `GET /v1/billing/ledger`: List the ledger. The account's credit movements, newest first: signup credit, top-ups, monthly credit, charges, corrections, refunds.
- `PUT /v1/billing/low-balance-alert`: Set the low-balance alert. Turn the low-balance email on or off and set its line (`threshold`, inside the plan list's `lowBalanceAlert.range`): one email each time the balance falls to it.
- `GET /v1/billing/payment-methods`: List the payment methods. The cards saved at the payment provider: brand, last 4, expiry, wallet, which is the default, and whether the last automatic charge on it was declined.
- `POST /v1/billing/payment-methods/manage`: Add or change a payment method. A link to the payment provider's portal, where a card is added, replaced or made the default (the provider has no API for those); it returns to the app's payment tab.
- `DELETE /v1/billing/payment-methods/{id}`: Remove a payment method. Remove a saved card.
- `GET /v1/billing/payments`: List the payments. The account's payments history, newest first: top-ups, auto top-ups and subscription payments (`paid`, `pending` while the provider processes one, `failed` for a declined charge or renewal), refunds (`refunded`) and credit never paid for (`credit`: the signup credit, a promo code's bonus, an adjustment).
- `GET /v1/billing/payments/{id}/document`: Get a payment's invoice or receipt. A link to the payment's invoice (a subscription) or receipt (a top-up), valid for a short while.
- `GET /v1/billing/plans`: List the plans. The visible plans with their current rates, prices, included credit, whether running work goes on in a grace period when the credit runs out (`graceOnZero`), limits and features, plus the top-up presets and range, the auto top-up and low-balance alert choices and ranges, the signup credit and the downgrade grace in days.
- `GET /v1/billing/portal`: Get the customer portal link. A link to the payment provider's customer portal (payment methods, invoices, receipts), valid for a short while.
- `POST /v1/billing/promo-codes/check`: Check a promo code. What a code gives `for` a `topup` (a bonus credit) or a `subscribe` (a discount off the first payment), before the checkout.
- `POST /v1/billing/subscription/cancel`: Cancel the subscription. Cancel at the end of the current period: nothing changes until then; after it the account moves to the default plan and unspent monthly credit is removed.
- `POST /v1/billing/subscription/interval`: Switch the billing interval. From the next period the subscription renews `month`ly or `year`ly (nothing is charged now); `subscription.pendingInterval` shows the switch until it applies.
- `DELETE /v1/billing/subscription/interval`: Keep the billing interval. Take back a scheduled interval switch.
- `POST /v1/billing/subscription/uncancel`: Keep the subscription. Take back a cancellation scheduled for the period end.
- `GET /v1/billing/usage`: Get the usage report. What the account spent per day (in `tz`), per source (`dashboard` or the API key that made the transcription, deleted recordings included) and per kind (`file`, `live`): audio seconds and dollars, with running transcriptions at their current amount.

## broadcasts

- `GET /v1/broadcasts`: List broadcasts. Broadcasts owned by the acting principal.
- `POST /v1/broadcasts`: Create a broadcast. Create a broadcast: the link listeners open (`code`), which a host can change later (the old one keeps working).
- `GET /v1/broadcasts/{id}`: Get a broadcast. One broadcast of the acting principal's, by id.
- `PATCH /v1/broadcasts/{id}`: Update a broadcast. Rename, change access/password, change the link (`code`; the links it had keep opening it), or update default capture settings.
- `POST /v1/broadcasts/{id}/archive`: Archive a broadcast. Archive the broadcast: hidden, its links dead, its data kept until it is restored or purged.
- `POST /v1/broadcasts/{id}/audio-sources`: Add an audio source. Give a broadcast a stream it can record from — a YouTube live, an internet radio address (`audioSources`).
- `DELETE /v1/broadcasts/{id}/audio-sources/{source}`: Remove an audio source. Take an audio source off a broadcast.
- `GET /v1/broadcasts/{id}/audio-sources/{source}/check`: Check an audio source. Whether an audio source can be recorded right now: the server opens it as a recording would — a YouTube link resolved to its live stream, a radio address connected, a playlist followed, the first audio decoded — and says whether audio came back (`state`).
- `POST /v1/broadcasts/{id}/purge`: Purge a broadcast. Delete an archived broadcast and everything in it, for good.
- `GET /v1/broadcasts/{id}/recordings`: List a broadcast's recordings. The broadcast's recordings.
- `POST /v1/broadcasts/{id}/recordings`: Start a recording. Start recording on the broadcast.
- `POST /v1/broadcasts/{id}/restore`: Restore a broadcast. Bring an archived broadcast back.
- `GET /v1/broadcasts/{id}/share-links`: List a broadcast's share links. Active share links of the broadcast.
- `POST /v1/broadcasts/{id}/share-links`: Create a share link. A named link ("Who is it for?") to the read-only public page.

## corrections

- `POST /v1/corrections/{id}/revert`: Revert a correction. Undo one correction.
- `GET /v1/recordings/{id}/corrections`: List corrections. Every correction made to the recording's transcript.
- `POST /v1/recordings/{id}/corrections`: Apply corrections. Apply a batch of word edits and line rewrites atomically; every target must be settled.
- `POST /v1/recordings/{id}/retranscribe`: Retranscribe a line. Read one line's audio again with the language forced, and apply what the recognizer hears as a line rewrite.

## jobs

- `GET /v1/recordings/{id}/job`: Get a job. The recording's transcription job: its state and progress (done/total segments, media seconds, pct).
- `GET /v1/recordings/{id}/job/preview`: Get a job's preview media. A job waiting in `cropping`: the media for the trim step to draw the waveform from in the browser.
- `POST /v1/recordings/{id}/job/retry`: Retry a job. Re-queue a failed job from its stored source.
- `POST /v1/recordings/{id}/job/start`: Start a cropped job. Release a job waiting in `cropping` (created with `crop: true`): the window of the source to transcribe, in seconds — an omitted bound is the start or the end of the file — then the job is queued.

## languages

- `GET /v1/languages`: List languages. Transcription, translation and voice lists with picker metadata.

## me

- `GET /v1/me`: Get the current account. Who the credential is: the acting principal, the person (`userId`) or API key (`apiKeyId`) behind it, the principals it may act for and a key's scopes.

## meta

- `GET /v1/health`: Check health. Liveness: 200 while this server is up.
- `GET /v1/openapi.json`: Get the OpenAPI document. This API's OpenAPI document, with this host in `servers`.

## realtime

- `GET /v1/realtime/capabilities`: Get realtime capabilities. What the realtime socket takes: supported languages, audio formats, and limits.
- `POST /v1/realtime/sessions`: Create a realtime session. Create a realtime session: a signed, stateless token for one WebSocket (`streamUrl`).

## recordings

- `GET /v1/recordings/{id}`: Get a recording. One recording, by id: for its owner, or any listener who can reach its broadcast or transcription.
- `POST /v1/recordings/{id}/archive`: Archive a recording. Archive the recording: hidden, its data kept.
- `GET /v1/recordings/{id}/audio`: Download a recording's audio. 302 to a freshly signed URL.
- `GET /v1/recordings/{id}/audio/clip`: Get an audio clip. A stretch of the audio as WAV (16-bit, 16 kHz, mono), available while the recording is still open — for replaying a line during live correction.
- `GET /v1/recordings/{id}/events`: Get a recording's event log. The recording's durable event log in order, each frame stamped with the wall time it was written — replays the recording exactly as the host saw it.
- `GET /v1/recordings/{id}/export`: Export a recording. A real file: JSON, SRT, XLSX (Excel workbook) or PDF, corrections included.
- `GET /v1/recordings/{id}/media-token`: Get a media token. The owner's credential for this recording's media URLs: pass it as `media=` to `/audio`, `/audio/clip` and `/voice/{sentence}` in place of `access_token`.
- `POST /v1/recordings/{id}/pause`: Pause a recording. Pause capture.
- `POST /v1/recordings/{id}/publish-token`: Create a publish token. Re-attach a publisher (reconnect or another device; takeover=true demotes the current one).
- `POST /v1/recordings/{id}/purge`: Purge a recording. Delete an archived recording for good.
- `POST /v1/recordings/{id}/restore`: Restore a recording. Bring an archived recording back.
- `POST /v1/recordings/{id}/resume`: Resume a recording. Resume a paused recording.
- `PATCH /v1/recordings/{id}/settings`: Update recording settings. Mid-recording capture settings (mode, language, labels).
- `PUT /v1/recordings/{id}/speakers/{idx}`: Name a speaker. Name a speaker of this recording.
- `POST /v1/recordings/{id}/stop`: Stop a recording. End capture; finalize runs asynchronously.
- `POST /v1/recordings/{id}/summarize`: Request a summary. Ask for the recording's AI title and summary.
- `GET /v1/recordings/{id}/summary`: Get a recording's summary. The title and summary as they stand — `ready` with both, `pending` while the engine is still writing them, `unavailable` on a server without a summariser.
- `GET /v1/recordings/{id}/transcript`: Get a transcript. Snapshot up to lastSeq; the backfill for subscribers (after=cursor).
- `GET /v1/recordings/{id}/translation`: Get a translation. Sentences of the transcript translated into `lang` (a translation target), by sentence id (`sentences`, comma separated): what a reader in another language pages through.
- `GET /v1/recordings/{id}/voice`: Get a recording's voice tracks. What this recording can be heard speaking, one row per language: rendered tracks (`sealed`) and their jobs, and the per-sentence clips a live audience left behind (`clips`, with the sentence ids and the voice that spoke them).
- `POST /v1/recordings/{id}/voice`: Render voice tracks. Render spoken tracks for a finished recording, one job per language (1–10 codes, each one /v1/languages says has a voice).
- `GET /v1/recordings/{id}/voice/{sentence}`: Get a spoken sentence. One spoken sentence, Ogg/Opus (`format=caf` for Apple's media stack).

## rtmp

- `GET /v1/rtmp`: Get RTMP status. The account's RTMP server URL and stream key for an encoder, whether one is sending audio on it right now and what (`audio`, e.g.

## search

- `GET /v1/search`: Search transcripts. Sentence search via the English pivot ∪ literal match; results rendered into lang on demand.

## share-links

- `PATCH /v1/share-links/{id}`: Update a share link. The share sheet's toggles: any of `label`, `allowDownload`, `allowExport`, `allowTranslate`.
- `DELETE /v1/share-links/{id}`: Revoke a share link. Revoke: the public page 404s at once.

## transcriptions

- `GET /v1/transcriptions`: List transcriptions. Transcriptions owned by the acting principal (file, link and live).
- `POST /v1/transcriptions`: Create a transcription. Transcribe a file or a link: creates the transcription, its recording and a server-owned job.
- `POST /v1/transcriptions/live`: Create a live transcription. Create a live transcription: captured as it is spoken — this device's microphone, or a stream the server pulls — rather than read from a file (`live: true`).
- `GET /v1/transcriptions/probe`: Probe a link. What a link is before it is transcribed: `live` — a YouTube live on air or scheduled, an endless HTTP stream, an HLS playlist with no end, a dynamic DASH manifest — belongs in a live transcription; `file` is transcribed as one; `unknown` could not be told.
- `GET /v1/transcriptions/{id}`: Get a transcription. One transcription of the acting principal's, by id.
- `PATCH /v1/transcriptions/{id}`: Update a transcription. Rename, or update default capture settings.
- `POST /v1/transcriptions/{id}/archive`: Archive a transcription. Archive the transcription: hidden, its links dead, its data kept until it is restored or purged.
- `PUT /v1/transcriptions/{id}/broadcasts/{broadcast}`: Attach a broadcast. Feed a broadcast from the live transcription `id`: listeners on the broadcast's link read the transcription while it records, and its recordings are listed with the broadcast's own.
- `DELETE /v1/transcriptions/{id}/broadcasts/{broadcast}`: Detach a broadcast. Stop feeding the broadcast from the live transcription `id`.
- `POST /v1/transcriptions/{id}/purge`: Purge a transcription. Delete an archived transcription and everything in it, for good.
- `GET /v1/transcriptions/{id}/recordings`: List a transcription's recordings. The transcription's recordings.
- `POST /v1/transcriptions/{id}/recordings`: Start a recording. Start recording a live transcription and mint a publisher realtime session (`streamUrl`, `sessionId`).
- `POST /v1/transcriptions/{id}/recordings/upload`: Upload a recording. A file or link recording in this transcription: no live phase, transcribed at full speed.
- `POST /v1/transcriptions/{id}/restore`: Restore a transcription. Bring an archived transcription back.
- `GET /v1/transcriptions/{id}/share-links`: List a transcription's share links. Active share links of the transcription.
- `POST /v1/transcriptions/{id}/share-links`: Create a share link. A named link ("Who is it for?") to the read-only public page.

## voices

- `GET /v1/voices`: List voices. The account's cloned voices, newest first.
- `POST /v1/voices`: Create a voice. Create a voice from a recorded sample and queue its training: multipart/form-data with a `sample` audio part and a `meta` JSON part.
- `GET /v1/voices/available`: List available voices. The voices that can speak a language, best first (`default` marks the one a recording that pins none gets).
- `POST /v1/voices/from-speaker`: Create a voice from a speaker. Create a voice from one speaker of a recording — no sample to upload, because the recording's own audio is the sample.
- `GET /v1/voices/preview`: Preview a voice. A few seconds of a voice speaking a language, Ogg/Opus (`format=caf` for Apple's media stack).
- `GET /v1/voices/{id}`: Get a voice. Training state: `training` / `ready` / `failed`, with `progress` and, when it failed, `error`.
- `PATCH /v1/voices/{id}`: Update a voice. Rename a voice, recolour it, or switch it off.
- `DELETE /v1/voices/{id}`: Delete a voice. Delete the voice, its recorded sample and anything trained from it.
- `GET /v1/voices/{id}/preview`: Preview a cloned voice. The cloned voice speaking, Ogg/Opus — `format=caf` for Apple's media stack, which will not play Ogg.
- `GET /v1/voices/{id}/sample`: Get a voice's sample. The audio this voice was made from, for its owner alone.