API overview

The API turns a link or an uploaded file into a Context. The web tool uses these same routes.

https://scribiz.com/api

Every path in these docs is relative to that base: POST /v1/context is POST https://scribiz.com/api/v1/context. The website and your own scripts use this one address, so a browser session stays on one origin. Sign-in sits under the same base, at https://scribiz.com/api/auth/.... The remote MCP server is a path of its own: https://scribiz.com/mcp.

How it works

Processing a video takes seconds to minutes, so the API is asynchronous:

1. POST /v1/context with a link or an upload. It checks the request, quotes the cost, and answers 202 at once with a job_id. If it cannot accept the job, it answers with an error before anything is queued.
2. Follow the job. GET /v1/jobs/:id always tells you where it stands, and when it is done, it holds the Context in result.
3. Optionally, GET /v1/jobs/:id/events streams progress as it happens.

The job is the source of truth. The event stream is a convenience. If you lose a connection, nothing is lost: ask for the job again.

A cached result still goes through a job. The quote says cached: true, the charge is 0, and the job finishes in under a second.

Conventions

• JSON. Requests and responses are JSON, in UTF-8, with Content-Type: application/json. Uploads are the exception.
• Names. The fields of the job API are snake_case: job_id, events_url, minutes_charged. The Context, the progress events and the job's error are the engine's own, in camelCase.
• Times. In the Context, times are seconds, as numbers rounded to milliseconds. Timestamps of the job and of the account, such as created_at and expires_at, are milliseconds since the Unix epoch.
• Ids. A job id looks like job_ and 22 letters and digits. An upload id starts with upl_. A key id starts with key_.
• Speakers have stable ids across a Context: S1, S2, and so on.
• Authentication is a bearer API key. See Authentication.
• Idempotency. Send an Idempotency-Key header with POST /v1/context. If the request is repeated with the same key and the same body, you get the same job back, with the header Idempotent-Replayed: true and "idempotent_replay": true in the body, not a second job and not a second charge. The same key with a different body is 422 with idempotency_key_reused. A key is 1 to 200 letters, digits, _, ., : or -. Use a new random value per logical request, such as a UUID.
• Usage is counted in minutes. See Minutes and billing.
• Errors have one shape, described on Errors and limits.

Versioning

The version is in the path: /v1. Within a version, changes are additive: new fields and new values can appear, and existing fields keep their meaning. Ignore fields you do not know.

The Context also carries its own version in schema. It is 1 today. Anything that would break a reader, such as removing a field, bumps it.

The routes

Each route is described on Endpoints. The shape of result is on The Context object. Failures and limits are on Errors and limits.

OpenAPI

GET /v1/openapi.json returns an OpenAPI 3.1 description you can feed to a code generator or an API client. If it and these pages ever disagree, the OpenAPI document describes what the server does today.

Not here yet

Webhooks, for example a call to your server when a job finishes, are not available. Poll the job or follow its events.