# Hushscript developer API

> A shape-frozen REST API for AI agents and automation: authenticate with a personal access token, save a card and buy minute packs, upload and transcribe recordings, poll jobs, read transcripts, and read workspace records. Operated by LW Agency Limited (Hong Kong).

Updated: 2026-10-14

## What this is
- The `/v1/` prefix on https://api.hushscript.com is a narrow, shape-frozen REST surface over the same account, balance, and minutes as the rest of the product. 38 method/path operations over 37 paths: account, billing (setup session, cards, packs, purchase, transactions, ledger, holds), uploads, jobs, transcripts, transcription context, agent account signup and credential rotation, workspace records (the workspace itself, members, matters, transcripts, usage, ledger, invoices, audit log, and CSV exports of usage, ledger, and audit), and four workspace writes: member rights, firm custody, and placing or lifting a legal hold.
- Full reference: https://api.hushscript.com/openapi.json (OpenAPI document, the source of truth for routes, parameters, and response schemas; served to any bearer token regardless of scope).
- Human-readable guide: https://hushscript.com/developers (quickstart, the end-to-end automation flow, scopes, endpoints, limits, error codes).

## Authentication
- A bearer token in the Authorization header: `Authorization: Bearer hsr1:<region>:pat.<id>.<secret>`. The account owner mints it once under Tokens at https://app.hushscript.com/account/mcp, choosing scopes and whether it may buy minutes. Tokens from the MCP server's OAuth sign-in work too; there is no separate token type for this API.
- An account can also open itself: POST /v1/agent/accounts begins a paid signup and POST /v1/agent/accounts/{signup_id}/claim grants the purchased pack and a token, with no welcome minutes. Hosted Checkout needs a browser, which an agent may drive; an issuer can still require authentication. POST /v1/agent/credentials/rotate is that account's own credential-recovery path. Full sequence: https://hushscript.com/automation/llms.txt. A human-created personal account can instead receive 30 free minutes when eligible after successful card verification, or with its first purchase if verification is unavailable. Either way, a token cannot mint, list, or revoke other tokens; at most 25 active tokens per account.
- Eleven caller-selectable scopes gate operations (account:read, billing, transcribe, transcripts:read, context, org:read and org:write on /v1/). A call outside its token's scopes fails with pat_scope_missing at 403. Billing additionally requires the token's billing flag and the account-wide switch. The separate `pat:rotate` scope is assigned only to an agent account's initial token and its successors; it cannot be selected when creating a token in the app.

## Automated flow with a token
1. GET /v1/account: balance_seconds, held_seconds, credits_expire_at (always null; minutes do not expire), card_on_file, data_region, limits.
2. POST /v1/billing/setup-session: returns checkout_url, session_id, expires_at. Open the URL in a browser you control and complete the hosted Stripe page. No charge; Hushscript never sees the card. Then GET /v1/billing/cards for the card id.
3. GET /v1/billing/packs, then POST /v1/billing/purchase with pack, quick_payment_method_id, idempotency_key. Charges the saved card off-session. Refusals: 4021 pat_purchase_requires_app (no card named, or declined), 4023 pat_purchase_requires_authentication (issuer challenge). Neither opens a page.
4. POST /v1/uploads with size_bytes, duration_seconds (15 s to 10 h), title, transcription_options, idempotency_key, and, for a token that belongs to a workspace, matter_code (free text, at most 64 characters, shown against the job in the workspace ledger and usage reports; a workspace whose matter policy is required refuses an upload without one, with org_matter_code_required). client_code is accepted and ignored: for a workspace caller the client is resolved from the matter. Answers job_id and presigned part URLs. PUT parts (32 MiB default), page more URLs from GET /v1/uploads/{job}/part-urls?start=n, heartbeat via POST /v1/uploads/{job}/heartbeat inside the 20 minute idle timeout, or PUT /v1/uploads/{job}/parts/{n} through the API as a fallback. Supported: mp3, m4a, mp4 or mov (the audio track is used, video tracks are skipped), wav, flac, ogg, opus, at most 5 GB; extract the audio from other video formats first.
5. POST /v1/uploads/{job}/complete with the n and etag of every presigned part. Poll GET /v1/jobs/{id} until state is done (or failed); read transcript_id.
6. GET /v1/transcripts/{id} for the metadata and full body; GET /v1/transcripts to page the list.
- Options: language_code or auto-detection, speaker_detection, medical_mode (+100%, language_code in en/es/fr/de), translation_targets (+25% per language), multichannel, keyterms_prompt, prompt, dictionary_ids, prompt_preset_id (from GET /v1/transcription-context).
- MCP-only for now: link import, transcript edits and deletion, Insights, exports, saving dictionaries and presets, settings. Same token at https://mcp.hushscript.com/mcp.

## Paging, limits, errors
- Every list takes limit and an opaque cursor, and answers next_cursor (null on the last page). Pass the cursor back unchanged.
- Human-account tokens have 1,200 requests a minute each; an agent account's token lineage shares 1,200 a minute across rotations. Stripe-calling billing routes reached with a token share 60 a minute per account: setup session, purchase, default-card changes, card removal, and card-list cache misses. Ordinary throttling answers HTTP 429 / 5000 rate_limited with Retry-After in seconds. Agent-account purchases and human-account PAT purchases share a cap of 3 attempts per rolling 24 hours per account; the agent signup purchase counts, as do declines or errors after reservation. Human browser-session purchases are exempt. The cap answers HTTP 429 / 4038 agent_purchase_capped with Retry-After.
- Errors are JSON {"error": "<slug>", "code": <number>}. Codes to handle: 2000 unauthorized, 2022 pat_forbidden, 2023 pat_scope_missing, 3001 insufficient_balance, 3002 card_declined, 3003 org_insufficient_balance, 4000 not_found, 4001 wrong_state, 4021 pat_purchase_requires_app, 4023 pat_purchase_requires_authentication, 1021 duration_out_of_range, 5000 rate_limited, 6001 provider_error, 9000 internal_error.
- No general transcription sandbox: ordinary calls use real accounts and purchases spend real money. `POST /v1/agent/accounts` alone accepts `dry_run: true` for validation without creating an account, Stripe session, or claimable signup.

## Also see
- Official SDKs and CLI over this API (TypeScript `@hushscript/sdk`, Python `hushscript`, Go `github.com/Hushscript/hushscript-sdk-go`, PHP `hushscript/sdk`, CLI `@hushscript/cli`): one call uploads a file, waits, and returns the transcript; an error after a purchase may have been sent carries its idempotency key, so a retry with the same key never charges twice: https://hushscript.com/sdks
- MCP interface, the same account behind 56 tools (visible according to token scopes): https://hushscript.com/mcp
- OAuth and token recipe: https://hushscript.com/auth.md
- Agent account setup and credential rotation: https://hushscript.com/automation
- Root manual: https://hushscript.com/llms.txt