# Audivo

> Podcast transcripts by API: send an episode, get the transcript.

- [Overview](https://docs.audivo.dev/index.md): Podcast transcripts by API — send an episode, get the transcript.
- [Quickstart](https://docs.audivo.dev/quickstart.md): One episode, one call, with curl.
- [Authentication](https://docs.audivo.dev/authentication.md): API keys, the one header every call sends, and what a refusal looks like.
- [Supported inputs](https://docs.audivo.dev/supported-inputs.md): What you can point Audivo at, what you cannot, and how a pointer becomes an episode.
- [Submit and poll](https://docs.audivo.dev/submit-and-poll.md): The one-episode path: submit, follow the job, read the result.
- [Price a selection](https://docs.audivo.dev/selections.md): Many episodes at once: quote a selection, confirm it as one group, read the results.
- [Upload your own audio](https://docs.audivo.dev/uploads.md): Transcribe audio you hold: a recording, or a show with no public feed whose audio you obtained yourself.
- [Cache behaviour](https://docs.audivo.dev/cache.md): Why the second caller pays less, what makes a hit, and what never counts as one.
- [Output formats](https://docs.audivo.dev/formats.md): The canonical JSON, the four renderings, the size limit, and the headers that travel with a raw body.
- [Connect an MCP client](https://docs.audivo.dev/mcp-server.md): Add Audivo to Claude, ChatGPT, Codex, Claude Code, Cursor, VS Code, and other MCP clients.
- [Using the MCP tools](https://docs.audivo.dev/mcp-tools.md): Ask for an episode and get its transcript back; price a batch first when you want to.
- [Errors](https://docs.audivo.dev/errors.md): Every error code the API returns, what it means, and whether a retry can help.
- [Limits](https://docs.audivo.dev/limits.md): What each plan allows: requests per minute, jobs in flight, selection sizes, and the audio caps everyone shares.
- [Languages](https://docs.audivo.dev/languages.md): Which languages are supported, what the support tiers mean, and when to pass one explicitly.
- [Changelog](https://docs.audivo.dev/changelog.md): What changed in the API, by contract version, newest first.
- [Credits](https://docs.audivo.dev/credits.md): One credit per audio minute, a ceiling you agree to before spending, and what happens to the money at every step.
- [Outbound fetching](https://docs.audivo.dev/outbound-fetching.md): What Audivo downloads on your behalf, from where, and the rules every fetch obeys.
- [Your data](https://docs.audivo.dev/data.md): What Audivo keeps about your account, for how long, who processes it, and how export and deletion work.
- [Create or attach to a transcription job, or get an instant result](https://docs.audivo.dev/api-reference/transcripts/create-or-attach-to-a-transcription-job-or-get-an-instant-result.md): The default way to transcribe one episode: one call, no quote first. Accepts exactly one of four input shapes (`url`, `feed_url` + `guid`, `episode_id`, or `upload_id`); supplying more than one, or fields from more than one shape, fails schema validation. Returns a synchronous result on a cache hit…
- [Poll job status, progress, and (once completed) the transcript](https://docs.audivo.dev/api-reference/transcripts/poll-job-status-progress-and-once-completed-the-transcript.md): Polls a job. Unlike the synchronous create and episode-read operations, `format` has **no default** here — omitting it and passing `?format=json` are different requests. Without `?format=` the response is `application/json` status only: the job status object, and `artifact` is never present, regardl…
- [Direct cached fetch of an episode's transcript](https://docs.audivo.dev/api-reference/transcripts/direct-cached-fetch-of-an-episodes-transcript.md): Fetches a compatible cached transcript for a canonical episode directly, without submitting a job. When no compatible cache object exists, returns an `EpisodeQuoteHint` — the same quote figures a dry run reports, but *without* `dry_run`, because this request was not a dry run — rather than creating…
- [Re-read a transcript this account has already paid for](https://docs.audivo.dev/api-reference/transcripts/re-read-a-transcript-this-account-has-already-paid-for.md): Serves the transcript behind a settled read, and **charges nothing**. `read_id` is the id a read was charged under: the `read_id` of a `cached_read` group member (`JobGroupCachedReadMember`), which a confirm creates and bills when the episode was already transcribed, or the `job_id` of a job that re…
- [Find shows by name](https://docs.audivo.dev/api-reference/catalog/find-shows-by-name.md): Free-text show search over Podcast Index: its exact-title search (`search/bytitle`) and its fuzzy term search (`search/byterm`) are issued together and merged, title hits first, each show once. The provider decides which shows match — no local fuzzy matcher — and the order is Audivo's, so the same n…
- [A category chart of a chosen size, capped by tier](https://docs.audivo.dev/api-reference/catalog/a-category-chart-of-a-chosen-size-capped-by-tier.md): The provider's chart for one category, of the size the caller asks for, clamped to the account tier's chart cap. The clamp is applied *before* the provider is called and is always reported in `size`, whether or not it bit: `requested` is what the caller asked for, `allowed` is what the tier permitte…
- [Episode metadata for a show](https://docs.audivo.dev/api-reference/catalog/episode-metadata-for-a-show.md): Episode metadata, publisher-transcript presence, cache availability, and a credit estimate per episode.
- [Resolve a podcast pointer to canonical IDs without creating a job](https://docs.audivo.dev/api-reference/catalog/resolve-a-podcast-pointer-to-canonical-ids-without-creating-a-job.md): Resolves an Apple Podcasts episode URL, or an RSS `feed_url` plus `guid`, to canonical `episode_id`/`show_id` without creating a job. Exactly one of `url` or (`feed_url` and `guid`) must be supplied; OpenAPI parameter schemas cannot express that cross-parameter rule, so a request supplying neither,…
- [Price a selection without spending](https://docs.audivo.dev/api-reference/quotes/price-a-selection-without-spending.md): Turns a chart or a list of named shows into a priced selection and records it. **Reserves nothing**: the quote holds no credit and creates no job; a separate confirm operation, keyed on `quote_id`, is what spends.
- [Spend what a quote priced, as one job group](https://docs.audivo.dev/api-reference/quotes/spend-what-a-quote-priced-as-one-job-group.md): Turns a recorded quote into a job group: one member per quoted entry, each either a transcription job reserved at the entry's ceiling or, for an entry priced as cached, a settled read at the price the quote gave it. This is the operation that spends.
- [Announce a file to upload](https://docs.audivo.dev/api-reference/uploads/announce-a-file-to-upload.md): Records what the caller knows about an audio file and returns a presigned PUT for it. The URL is signed against the declared SHA-256, so S3 refuses a body whose hash differs; the API never reads the bytes. Send the file with exactly the `put_headers` returned. Then transcribe it with `POST /v1/trans…
- [List the caller's job groups, newest first](https://docs.audivo.dev/api-reference/groups/list-the-callers-job-groups-newest-first.md): The caller's own groups and nobody else's, newest first. A summary per group — its status, size, and timestamps — never its members: read a group for those. `limit` bounds the page; there is no cursor in 0.3.0 (`next_cursor` is always `null`), so a caller with more history than one page sees its new…
- [Read one job group's rollup](https://docs.audivo.dev/api-reference/groups/read-one-job-groups-rollup.md): One request for the whole group: member counts by state, the credits it holds reserved and has settled and released, and every member — each job with its id and state, each cached read with the id it was charged under. Only for a group the caller's own account owns: another account's group id answer…
- [Cancel a group's members that have not started](https://docs.audivo.dev/api-reference/groups/cancel-a-groups-members-that-have-not-started.md): Cancels every member still `validating` or `queued` and releases each one's reservation exactly once; a member a worker already owns is left to run and to settle or release on its own, exactly as `DELETE /v1/transcripts/{job_id}` leaves a claimed job. Idempotent: a repeat finds nothing left to cance…
- [Account credit balance and period usage](https://docs.audivo.dev/api-reference/account/account-credit-balance-and-period-usage.md): The account's balance, what it has spent in the current reporting period, and that spend day by day.
- [Exact rate/concurrency/duration/size limits for the caller's tier](https://docs.audivo.dev/api-reference/account/exact-rateconcurrencydurationsize-limits-for-the-callers-tier.md): Published as exact numbers, never "unlimited", so callers can build correct retry/backoff behavior. Every figure is a pure function of the caller's tier, so this operation reads no account row and answers even when one cannot be read.
- [Pinned engine route and support tier per language](https://docs.audivo.dev/api-reference/account/pinned-engine-route-and-support-tier-per-language.md): Support tier (`benchmarked | supported | best_effort`) and timing capability per language; no diarization field at launch. A caller relying on automatic detection to reach a language outside the default engine's coverage must instead pass `language` explicitly on `POST /v1/transcripts`.
- [The account's recent API requests and what each one cost](https://docs.audivo.dev/api-reference/account/the-accounts-recent-api-requests-and-what-each-one-cost.md): One entry per request the account made: when it arrived, the endpoint it called, how it ended, and the credits it was charged. Newest first, paged with `limit` and `cursor`.
- [Establish the signed-in user's Audivo session](https://docs.audivo.dev/api-reference/session/establish-the-signed-in-users-audivo-session.md): Resolves the access token's Cognito subject to a Audivo account, creating the account and its one free credit grant if no row exists yet, and answers with the identity a session then carries.
- [List API keys for the account](https://docs.audivo.dev/api-reference/api-keys/list-api-keys-for-the-account.md): Key metadata only; never returns stored plaintext.
- [Create a labeled API key](https://docs.audivo.dev/api-reference/api-keys/create-a-labeled-api-key.md): Returns the plaintext secret exactly once.
- [Revoke an API key](https://docs.audivo.dev/api-reference/api-keys/revoke-an-api-key.md): Revokes immediately; idempotent.
- [Read a pending connection request](https://docs.audivo.dev/api-reference/connected-apps/read-a-pending-connection-request.md): What the consent page shows for an app asking to connect: the app, where its authorization code would be sent, and what the scope allows. Read back from the request the authorization endpoint recorded — nothing here comes from the page's own URL. `client.verified` is `true` only when something the a…
- [Approve or decline a connection request](https://docs.audivo.dev/api-reference/connected-apps/approve-or-decline-a-connection-request.md): The signed-in account holder's answer. Approving connects the app to this account: a one-use authorization code and the connection (`grant_id`) are created and the request consumed in one write, and `redirect_to` is the app's redirect carrying `code`, `state`, and `iss`. Declining consumes the reque…
- [List the account's connected apps](https://docs.audivo.dev/api-reference/connected-apps/list-the-accounts-connected-apps.md): Every app connected through OAuth, newest first, revoked ones included. `last_used_at` is when the connection last obtained a token.
- [Revoke a connected app](https://docs.audivo.dev/api-reference/connected-apps/revoke-a-connected-app.md): Ends the connection: every access token it issued stops working within five minutes, the same bound as a revoked API key, and it can refresh nothing. Idempotent; available on an account on hold.
- [Create a Stripe Checkout session](https://docs.audivo.dev/api-reference/billing/create-a-stripe-checkout-session.md): Creates a Stripe Checkout session for one paid tier and answers with the URL to send the customer to. The caller names a *tier*; the price behind it is resolved server-side from the stable Stripe lookup key, never sent by the caller — see `CheckoutRequest` for why. Plan switching is rate-limited to…
- [Create a Stripe Customer Portal session](https://docs.audivo.dev/api-reference/billing/create-a-stripe-customer-portal-session.md): Customer Portal session with tested cancellation behavior: renewal stops immediately while paid-period access is preserved unless the customer explicitly requests eligible immediate termination.
- [Normalized invoice/payment history](https://docs.audivo.dev/api-reference/billing/normalized-invoicepayment-history.md): The caller's own invoices, newest first, paged with `limit` and `cursor`. An account that has never paid for anything has an empty page rather than an error — including one still carrying the placeholder customer a signup writes, which has no Stripe history to read.
- [The account's stored billing address](https://docs.audivo.dev/api-reference/billing/the-accounts-stored-billing-address.md): The billing address this account has saved, or `null` when it has saved none.
- [Store the account's billing address](https://docs.audivo.dev/api-reference/billing/store-the-accounts-billing-address.md): Replaces the stored billing address with the one sent. A whole address, not a patch: a partial update of a postal address is how a customer who moves from a country with states to one without ends up with a province that is no longer theirs.
- [Whether this account tops itself up, and on what terms](https://docs.audivo.dev/api-reference/billing/whether-this-account-tops-itself-up-and-on-what-terms.md): The account's auto-recharge setting and the figures it would use.
- [Turn auto-recharge on or off](https://docs.audivo.dev/api-reference/billing/turn-auto-recharge-on-or-off.md): Switches auto-recharge on or off. Switching it on also clears a recorded decline, which is how a customer retries after fixing their card.
- [Refund an eligible unused paid-credit lot](https://docs.audivo.dev/api-reference/billing/refund-an-eligible-unused-paid-credit-lot.md): **Declared, not routed.** No deployed method answers this operation yet: Stripe runs in test mode and no real money has moved, and the refund policy text it depends on is not written. The shape stands so a client can be built against it; a call today reaches the edge's own 403 for an unmapped method…
- [Export the account's portable data](https://docs.audivo.dev/api-reference/data/export-the-accounts-portable-data.md): Generates the paid-beta account export and returns an expiring download.
- [Delete the account and account-linked data](https://docs.audivo.dev/api-reference/data/delete-the-account-and-account-linked-data.md): Revokes access and deletes account-linked data under the disclosed retention/shared-cache policy. Does not promise deletion of a shared public-podcast cache object still used by other accounts.

## OpenAPI Specs

- [openapi](/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.