# KolWrite platform API > REST API for the KolWrite platform at https://api.kolwrite.com: upload audio or video, create transcription jobs with word timings and speakers, export text, JSON, SRT or VTT, share results, and call OpenAI-compatible managed AI endpoints (chat completions, responses, embeddings, short-clip transcription). Personal access tokens (`kol_...`) with per-endpoint scopes. Documentation: https://kolwrite-docs.pages.dev. Not this API? The credits API at https://app.kolwrite.com (header `x-api-key`) is a different API, documented at https://console.kolwrite.com/llms.txt. This file covers only the platform API at https://api.kolwrite.com. Prefer the Markdown sources below over crawling the HTML pages. ## When to use which call - Transcript of a file with word timings and speakers: `POST /api/v1/media/upload-session` (with `filename`, `file_size_bytes`, `content_type`), PUT the bytes to `data.upload_url`, `POST /api/v1/media/complete` with `finalize_token` (returns `data.media_id`), `POST /api/v1/jobs` with `{"type": "transcription", "input": {"type": "media_ref", "media_id": "..."}, "profile": "oracle"}`, poll `GET /api/v1/jobs/{job_id}` until `status` is `succeeded`, then `GET /api/v1/jobs/{job_id}/export?format=json`. - The JSON export is `{"data": "", "meta": {...}}`: parse `data` again. It holds `segments` (`start`, `end` in seconds, `text`, `speaker`, `words[]` with `text`, `start`, `end`). - Subtitles: `export?format=srt` or `format=vtt`; `include_speakers`, `max_chars_per_entry` and `highlight_words` shape the SRT. SRT and VTT downloads need a Plus plan or higher (HTTP 403, code `subtitle_export_requires_plus`). - Subtitles in another language: `options.target_language` on the job. - Plain text: `export?format=text`. - Text for a short voice clip, no job: `POST /api/v1/ai/openai/audio/transcriptions` (multipart `file`, `model`, optional `want_words`). - Chat, responses, embeddings: the OpenAI-compatible endpoints under `https://api.kolwrite.com/api/v1/ai/openai` (scope `ai:use`; models `kw-auto`, `kw-fast`, `kw-pro`; `GET /models` lists what the token can use). Guide: https://kolwrite-docs.pages.dev/openai-compatible.md. - A saved turn in the KolWrite app's general or transcript Copilot: `POST /api/v1/ai/conversations/copilot/messages` (scope `copilot:write`; send a unique `Idempotency-Key`). - The saved, versioned transcript: `GET /api/v1/jobs/{job_id}/artifacts` and `GET /api/v1/artifacts/{artifact_id}` (scope `transcripts:read`). - Credit balance: `GET /api/v1/billing/balance` (scope `billing:read`). - A public link to a transcript: `POST /api/v1/shares` (scope `shares:write`). - Model profiles: `GET /api/v1/models`. - Always send an `Idempotency-Key` when creating a job. Retry `429`, `502`, `503`, `504` with backoff; do not retry `401`, `403` or validation errors. ## Guides (Markdown) - [AI agents](https://kolwrite-docs.pages.dev/agents.md): token from an environment variable, scopes, upload to job to transcript to SRT, a complete Python example, rules for agents. - [OpenAI-compatible endpoints](https://kolwrite-docs.pages.dev/openai-compatible.md): swap the base URL in an OpenAI SDK; endpoints, models, requirements. - [Quickstart](https://kolwrite-docs.pages.dev/quickstart.md): create a token, upload, transcribe, poll, export, share (curl). - [Authentication and scopes](https://kolwrite-docs.pages.dev/authentication.md): personal access tokens, every scope, errors. - [Errors and rate limits](https://kolwrite-docs.pages.dev/errors.md): status codes, retry guidance, rate-limit headers. ## Reference - [OpenAPI 3.1](https://kolwrite-docs.pages.dev/openapi.json): the complete public v1 contract; each operation lists its required scope in `x-required-scope`. - [API reference](https://kolwrite-docs.pages.dev/reference.html): the interactive reference. - Site: https://kolwrite-docs.pages.dev/ ## Guides in other languages (Markdown) - עברית: https://kolwrite-docs.pages.dev/locales/he/quickstart.md, https://kolwrite-docs.pages.dev/locales/he/authentication.md, https://kolwrite-docs.pages.dev/locales/he/errors.md, https://kolwrite-docs.pages.dev/locales/he/agents.md, https://kolwrite-docs.pages.dev/locales/he/openai-compatible.md - العربية: https://kolwrite-docs.pages.dev/locales/ar/quickstart.md, https://kolwrite-docs.pages.dev/locales/ar/authentication.md, https://kolwrite-docs.pages.dev/locales/ar/errors.md, https://kolwrite-docs.pages.dev/locales/ar/agents.md, https://kolwrite-docs.pages.dev/locales/ar/openai-compatible.md - Español: https://kolwrite-docs.pages.dev/locales/es/quickstart.md, https://kolwrite-docs.pages.dev/locales/es/authentication.md, https://kolwrite-docs.pages.dev/locales/es/errors.md, https://kolwrite-docs.pages.dev/locales/es/agents.md, https://kolwrite-docs.pages.dev/locales/es/openai-compatible.md - Français: https://kolwrite-docs.pages.dev/locales/fr/quickstart.md, https://kolwrite-docs.pages.dev/locales/fr/authentication.md, https://kolwrite-docs.pages.dev/locales/fr/errors.md, https://kolwrite-docs.pages.dev/locales/fr/agents.md, https://kolwrite-docs.pages.dev/locales/fr/openai-compatible.md - Deutsch: https://kolwrite-docs.pages.dev/locales/de/quickstart.md, https://kolwrite-docs.pages.dev/locales/de/authentication.md, https://kolwrite-docs.pages.dev/locales/de/errors.md, https://kolwrite-docs.pages.dev/locales/de/agents.md, https://kolwrite-docs.pages.dev/locales/de/openai-compatible.md - Português: https://kolwrite-docs.pages.dev/locales/pt/quickstart.md, https://kolwrite-docs.pages.dev/locales/pt/authentication.md, https://kolwrite-docs.pages.dev/locales/pt/errors.md, https://kolwrite-docs.pages.dev/locales/pt/agents.md, https://kolwrite-docs.pages.dev/locales/pt/openai-compatible.md - Italiano: https://kolwrite-docs.pages.dev/locales/it/quickstart.md, https://kolwrite-docs.pages.dev/locales/it/authentication.md, https://kolwrite-docs.pages.dev/locales/it/errors.md, https://kolwrite-docs.pages.dev/locales/it/agents.md, https://kolwrite-docs.pages.dev/locales/it/openai-compatible.md - Русский: https://kolwrite-docs.pages.dev/locales/ru/quickstart.md, https://kolwrite-docs.pages.dev/locales/ru/authentication.md, https://kolwrite-docs.pages.dev/locales/ru/errors.md, https://kolwrite-docs.pages.dev/locales/ru/agents.md, https://kolwrite-docs.pages.dev/locales/ru/openai-compatible.md ## Facts - Base URL https://api.kolwrite.com. Send `Authorization: Bearer kol_...` or `X-API-Key: kol_...`. - API access is enabled per account; a person creates the token in the KolWrite app (Settings, Account, API access). Tokens never expire unless an expiry is set. - AI endpoints need a token created from a signed-in KolWrite app session, the `ai:use` scope and an account that accepted the current third-party AI disclosure (otherwise HTTP 428, code `legal_acceptance_required`). They spend credits per token of usage. - Saved Copilot turns use `copilot:write`; transcript targets require access to the workspace file, and shared transcript turns require workspace write access. They currently spend the API-key owner's credits. - Speakers only: keep a transcript you already have (timed lines, for example a saved live session) word for word and add speakers with `"profile": "speakers-only"` and `options.reuse_transcript_segments`; only the diarization add-on is charged (`regular` 0.25, `pro` 1.00 credit per minute). See https://kolwrite-docs.pages.dev/openapi.json. - Live transcription: `GET /api/v1/models` gives every transcription model a `live` block (where it runs, `request_model`, estimated credits per minute of speech). - Prices are not listed here; the credits API's prices are at https://console.kolwrite.com/llms/pricing.md. ## The KolWrite / KolHive family Made by ITANU STUDIOS LTD (Israel). - [KolWrite](https://www.kolwrite.com/): transcription for meetings, calls, lectures and interviews; subtitles and captions (SRT); translation; on-device and cloud models. Web app: https://beta.kolwrite.com/ - [KolWrite API](https://console.kolwrite.com/): REST speech-to-text with word timings, speaker labels and SRT, for developers and AI agents; https://console.kolwrite.com/llms.txt, https://console.kolwrite.com/agent-instructions.md and https://console.kolwrite.com/openapi.json. Platform API reference: https://kolwrite-docs.pages.dev/ - [KolWrite Enterprise](https://enterprise.kolwrite.com/): KolWrite for organizations: members, billing and audit logs. - [KolHive](https://www.kolhive.com/): an AI OS: your own desktop with real apps and your files, and any AI doing the work in it, on macOS, Windows, Linux, iOS, Android and the web. In closed testing; web demo without an account: https://demo.kolhive.com/ - KolChat: end-to-end encrypted chat, calls and meetings, being prepared for KolHive. Not publicly released yet.