API endpoints

Base URL https://scribiz.com/api. Every path below is relative to it: POST /v1/context is POST https://scribiz.com/api/v1/context. Send Authorization: Bearer <key> on every call except /health, /v1/status, /v1/openapi.json and the anonymous web tool. For the shape of errors, see Errors and limits.

Jobs

POST /v1/context

Create a job that builds the Context of a link or an upload. The call checks the request, resolves the link, quotes the cost and checks your plan, then queues the job. Nothing is queued if any step refuses.

The body is JSON, up to 64 KB, and takes only the fields below. Send exactly one of url and upload_id.

An anonymous request that sets an accounts-only option is 403 with account_required.

curl https://scribiz.com/api/v1/context \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \  -d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw", "mode": "auto"}'

HTTP/1.1 202 AcceptedLocation: /v1/jobs/job_2DUafpGltJTqVKlAYlIREmContent-Type: application/json

{  "estimate": {    "cached": false,    "charges_as": "captions",    "media_seconds": 19,    "minutes": 0.031667,    "tiers": ["captions", "synthesis"]  },  "events_url": "/api/v1/jobs/job_2DUafpGltJTqVKlAYlIREm/events",  "job_id": "job_2DUafpGltJTqVKlAYlIREm",  "mode": "auto",  "queue_position": 1,  "result_url": "/api/v1/jobs/job_2DUafpGltJTqVKlAYlIREm",  "status": "queued"}

A cached result still goes through a job and finishes almost at once. A request that could not be accepted fails before a job exists:

A link that needs a login, such as an Instagram post, is refused here with source_auth_required, not reported later on the job. See Errors and limits.

GET /v1/jobs/:id

The state of a job. When it succeeded, result is the Context.

{  "attempt": 1,  "cache_hit": null,  "cancel_requested": false,  "created_at": 1791094927185,  "error": null,  "estimate": { "cached": false, "charges_as": "audio", "media_seconds": 12.120726, "minutes": 0.202012, "tiers": ["audio", "synthesis"] },  "events_url": "/api/v1/jobs/job_7b9rgMRwWjy1mIoS64A8CU/events",  "expires_at": 1793686927185,  "finished_at": null,  "input": { "kind": "upload", "upload_id": "upl_1MOSdD3kCZtK72deTv7Dw6" },  "job_id": "job_7b9rgMRwWjy1mIoS64A8CU",  "minutes_charged": null,  "mode": "audio",  "progress": 0.88,  "result": null,  "result_url": "/api/v1/jobs/job_7b9rgMRwWjy1mIoS64A8CU",  "stage": "synthesize",  "started_at": 1791094927185,  "status": "running"}

A job that belongs to another account is 404 with not_found, the same as one that does not exist. An expired job is 410 with job_expired. A recording with no speech, such as music, is a normal succeeded job with result.transcript set to null and the warning NO_SPEECH_DETECTED.

GET /v1/jobs/:id/events

A stream of server-sent events for one job, for a live progress display.

curl -N https://scribiz.com/api/v1/jobs/job_2DUafpGltJTqVKlAYlIREm/events \  -H "Authorization: Bearer $SCRIBIZ_API_KEY"

• Each event is three lines: id: <number>, event: <type> and data: <JSON>. The data is one object. These are the same objects as in The JSON protocol: start, plan, stage, progress, chunk, retry, warning, partial, usage, cache, done and error. The API adds queued, started (once per attempt) and requeued.
• The stream starts with retry: 3000, and then replays every stored event.
• Reconnect with a Last-Event-ID header, or ?last_event_id=, and the stream replays what you missed, then continues.
• A : ping line, a comment, is sent every 15 seconds.
• The stream ends after exactly one done or one error. A canceled job ends with an error whose code is CANCELLED.
• progress and partial events are thinned to about one every 400 milliseconds per step. A job keeps at most 2,000 events.
• An owner can hold 8 streams open at once. More is 429 with too_many_streams.
• A partial event says how much of the video the transcript covers so far, so a page can show text while the rest is still running.

A stream that drops is not a failed job. Read GET /v1/jobs/:id to find out.

DELETE /v1/jobs/:id

Cancel a running job, or delete the stored result of a finished one. Only the account or anonymous caller that created the job can do it. Anyone else gets 403 with not_owner.

curl -X DELETE https://scribiz.com/api/v1/jobs/job_0fVFR5QoOu2P2t3QkDkj2H \  -H "Authorization: Bearer $SCRIBIZ_API_KEY"

• A queued job is canceled at once and answers 200.
• A running job is aborted. The call waits up to 10 seconds and answers 200 with the final job, whose status is canceled and whose error.code is CANCELLED. If it is still winding down, the answer is 202. Nothing is charged for a canceled job.
• A finished job has its result erased and answers 200 with { "job_id": "...", "status": "deleted" }. A later GET answers 404.

Uploads

PUT /v1/uploads

Upload a media file to use in a job. The request body is the file itself, not JSON and not multipart. It takes audio and video files.

{  "bytes": 73264,  "duration_seconds": 12.120726,  "expires_at": 1791097083297,  "file_name": "speech.mp3",  "has_audio": true,  "has_video": false,  "mime": "audio/mpeg",  "upload_id": "upl_4dEjVvJnlzplZvFcA2PULr"}

ffprobe must name a real media container. Scribiz decides that from the file, not from the Content-Type or the extension. A playlist or a text file is refused with 415. An upload is kept for one hour. Pass its id to POST /v1/context in that time. The file belongs to one job: it is removed when the job succeeds, and kept for a retry when it fails.

POST /v1/transcribe

A shortcut that uploads a file and creates a job in one request. It takes a multipart/form-data body with the file in file, and optional mode, language, options (a JSON string) and turnstile_token. It has the same 100 MB cap, and answers like POST /v1/context plus upload_id. If the job is refused after the file arrived, the error carries upload_id, so you can call POST /v1/context without sending the file again.

curl https://scribiz.com/api/v1/transcribe \  -H "Authorization: Bearer $SCRIBIZ_API_KEY" \  -F "[email protected]" \  -F "mode=audio"

The server buffers a multipart body in memory, about three times the size of the file, and parses one at a time. Prefer PUT /v1/uploads.

Questions

POST /v1/ask

Ask a question about a Context you already have. It costs 0.1 minutes.

{  "answer": "The speaker mentions that the cool thing about elephants is that they have really, really long trunks, and adds that that is pretty much all there is to say about them.",  "citations": [    { "start": 5.318, "end": 14.367, "text": "the cool thing about these guys is that they have really... really really long trunks and that's cool" },    { "start": 16.881, "end": 18.881, "text": "and that's pretty much all there is to say" }  ],  "minutes_charged": 0.1}

citations point at real transcript segments. This route never starts the on-screen layer: for a question about the picture on a Context that has none, notes says so. A job that has not succeeded is 409 with job_not_ready. Anonymous callers get 5 questions a day, then 429 with anonymous_limit.

Account

GET /v1/me

The account behind the key, its plan and its minutes. Without a credential it describes the anonymous limits instead.

{  "anonymous": false,  "auth": { "keyId": "key_GDAeFMIBQ2lh", "scopes": "all", "via": "api_key" },  "entitlement": {    "lifetimeMac": false,    "minutesIncluded": 30,    "minutesTopup": 0,    "period": { "end": 1793491200000, "key": "2026-10-01", "start": 1790812800000 },    "plan": "free",    "planUntil": null,    "source": "none"  },  "limits": {    "apiKeys": { "active": 1, "max": 10 },    "maxConcurrentJobs": 2,    "maxVideoSeconds": 7200,    "minutesPerPeriod": 30,    "proxy": { "maxInflightCalls": 4, "requestsPerMinute": 60, "uploadBytesPerDay": 1073741824 }  },  "plan": "free",  "usage": {    "audioSeconds": 0,    "costMicros": 0,    "includedRemaining": 30,    "minutesRemaining": 30,    "minutesTopup": 0,    "minutesUsed": 0,    "period": "2026-10-01",    "periodEnd": 1793491200000,    "periodStart": 1790812800000  },  "user": { "email": "[email protected]", "id": "xEPzDpPvurJRuQneA7TXzN9ldow7Xo25", "name": "" }}

For an anonymous caller, usage has day, minutesUsed, minutesRemaining, captionJobsUsed, captionJobsRemaining and resetsAt, and limits has minutesPerDay, captionJobsPerDay, asksPerDay, maxVideoSeconds, maxConcurrentJobs and resultTtlHours.

Keys

GET /v1/keys

List your keys. The key itself is never returned again, only its prefix and its last four characters. It works with a key that has the all scope. See API authentication for the response.

POST /v1/keys

Create a key. It needs a signed-in session, which the dashboard has. A key cannot call it: that is 403 with session_required. The response is the only time you see the key.

{  "createdAt": 1791093434663,  "createdVia": "dashboard",  "deviceLabel": null,  "expiresAt": null,  "id": "key_T09PW9orWbQL",  "key": "sbz_live_your_new_key_here",  "lastUsedAt": null,  "last4": "UYZC",  "name": "mcp agent",  "prefix": "sbz_live_",  "scopes": "mcp"}

An account can hold up to 10 active keys. The next is 409 with key_limit_reached.

DELETE /v1/keys/:id

Revoke a key. It needs a signed-in session. The key stops working at once, and everywhere within about a minute. A key that is not yours is 404.

Other routes

GET /v1/status

How the service is doing, for a status page. No key needed. The answer is cached for 10 seconds.

{  "free_tier": { "listen_watch": "open" },  "ok": true,  "queue": { "capacity": 2, "queued": 0, "running": 0 },  "sources": [    { "avg_seconds": 8.2, "blocked": 0, "failed": 0, "jobs": 1, "source": "youtube", "succeeded": 1, "success_rate": 1 }  ],  "status": "operational",  "time": 1791093526634,  "window_hours": 24}

sources covers the last 24 hours. A failure that is the caller's, such as a private video or no minutes, does not count against a source. free_tier.listen_watch is paused when Listen and Watch are switched off for anonymous callers. status is degraded then.

GET /v1/openapi.json

The OpenAPI 3.1 description of the API. No key needed.

GET /health

Returns {"ok":true} when the service is up. It reports nothing else.

POST /v1/billing/checkout

Starts a purchase and answers where to send the buyer: { "url", "sessionId", "expiresAt", "amount", "currency", "earlyBird" }. url is a Stripe payment page, and amount (in cents, before tax) is what that page charges. Send plan (pro, mac-lifetime or topup), with interval for Pro and pack for a top-up, and never a price. It needs a signed-in session, not an API key. While nothing is on sale it answers 501 with the code billing_not_configured.

DELETE /v1/account

Delete your account and everything it owns: results, keys and files at Google. It needs a signed-in session.

/mcp

The remote MCP server. It speaks the Streamable HTTP transport and takes the same API keys. It also answers without a key, inside a small daily allowance. See MCP.

Routes that are not part of the API

These exist for Scribiz's own apps. Do not build on them. They can change without notice.

• POST /v1/cli/exchange swaps a browser approval for an API key. It is the last step of command-line sign-in (scribiz login), and the key it returns is the one the CLI saves.
• /v1/gemini/* is a metered, allow-listed route that the CLI uses when it is signed in to a Scribiz account. Usage is measured from what the model reports, not from anything the caller says.
• https://scribiz.com/api/auth/* is sign-in for the website and the device flow. The code you confirm is entered at https://scribiz.com/login/device.