KolWrite KolWrite Developers

Authentication & Scopes

Personal access tokens

API access is self-serve: once your account has bought credits, turn it on in Settings → Account → API access. Calls spend your credits.

Create tokens in the KolWrite app under Settings → Account → API access. Tokens look like kol_..., are shown once at creation, and act as you: they see your files, spend your credits, and honor your plan limits. Send the token either way — both are equivalent:

Authorization: Bearer kol_...
X-API-Key: kol_...

Scopes

A token can only call endpoints covered by its granted scopes. Every operation in the reference is annotated with its required scope (x-required-scope in the OpenAPI spec).

ScopeGrants
files:readList and download files, folders, media, and uploads; read storage usage
files:writeUpload files, register media, create or update folders and workspaces
jobs:readRead job status, queue position, results, and job artifacts
jobs:writeCreate and cancel jobs (transcription, caption burn); reorder the queue
transcripts:readRead transcripts, versions, and export download URLs
transcripts:writeSave new transcript versions and restore previous ones
ai:useUse KolWrite managed AI (chat, embeddings, fast transcription); spends credits
copilot:writeRun metered AI turns and save them in general or authorized transcript Copilot history
shares:readList and inspect public share links
shares:writeCreate, update, rotate, and revoke public share links
devices:readList signed-in device sessions
devices:writeLog out device sessions
account:readRead feature flags and app experience preferences
account:writeUpdate app experience preferences
billing:readRead credit balance, ledger, and grants

Presets in the app: Read only (all *:read), Automation (files:*, jobs:*, transcripts:read, billing:read), Full access.

Scope errors

Missing scope on a covered endpoint:

{"detail": {"code": "insufficient_scope",
            "message": "This endpoint requires the 'jobs:write' scope",
            "required_scope": "jobs:write"}}

Endpoint outside the public token surface:

{"detail": {"code": "pat_route_not_allowed",
            "message": "This endpoint is not available to personal access tokens"}}

Both return HTTP 403. Invalid or revoked tokens return HTTP 401 with invalid_api_key.

Credits and billing

Jobs reserve credits when created and settle on completion; AI calls meter per token usage. Check spend with the billing:read scope via GET /api/v1/billing/balance and GET /api/v1/billing/ledger.

Limits and spending

Credits are the hard stop: paid calls (transcription jobs and the AI proxy) spend credits, and with none left they return HTTP 402 insufficient_credits.

Your usage tier rises by itself with the credits you have bought and your account's age (Start, Build, Scale, Established). Each tier sets a monthly ceiling, requests per minute and parallel requests per key.

In the app you can set a monthly budget for the account and, per key, a monthly cap, allowed IP addresses and an expiry. Past a budget or cap, paid calls return HTTP 402 api_monthly_budget_reached or api_key_cap_reached; too many requests return HTTP 429 with Retry-After.

Unusual spend first sends you an email; only extreme spikes pause a key, and you can resume it in the app. Rotating a key can keep the old one working for up to 7 days.