KolWrite API for AI agents
How to let an AI agent (Claude Code, Codex, Cursor, or a script of your own) turn recordings into transcripts, SRT subtitles and word timings with the KolWrite platform API at https://api-prod.kolwrite.com. A person creates a token once; the agent reads it from an environment variable and calls plain HTTPS. No SDK is needed.
This is the platform API with kol_ tokens. The credits API at https://app.kolwrite.com (header x-api-key) is a different API, described at https://console.kolwrite.com/llms.txt.
If you would rather install than write the calls yourself, the API console has ready-made installs for the credits API: an MCP server for Claude Code, Codex, Cursor and Gemini CLI, an agent skill, and kolwrite.py, a one-file Python client. They use an API key from console.kolwrite.com, not a kol_ token. Start at https://console.kolwrite.com/agents/ ; the files are https://console.kolwrite.com/cli/kolwrite.py and https://console.kolwrite.com/skills/kolwrite-transcribe.zip.
1. Give the agent a token
- API access is self-serve: any account that has bought credits turns it on in the app. Calls spend the account's credits within its budget and key caps.
- A person creates the token in the KolWrite app (Settings → Account → API access → Create token) and picks the smallest set of scopes. The secret (
kol_...) is shown once. - Put it in an environment variable and keep it out of prompts, logs and git.
| Task | Scopes |
|---|---|
| Transcribe and export | files:write, jobs:write, jobs:read, transcripts:read |
| Also check the credit balance | add billing:read |
| OpenAI-compatible endpoints | ai:use (spends credits; not part of the app's Automation preset) |
| Create share links | add shares:write |
Paste this into AGENTS.md, CLAUDE.md or .cursorrules:
## KolWrite platform API
- Base URL https://api-prod.kolwrite.com. The token is in the environment variable KOLWRITE_TOKEN: send it as "Authorization: Bearer $KOLWRITE_TOKEN" and never print it.
- Flow: POST /api/v1/media/upload-session, PUT the bytes to data.upload_url, POST /api/v1/media/complete, POST /api/v1/jobs, poll GET /api/v1/jobs/{job_id} until status is succeeded, then GET /api/v1/jobs/{job_id}/export?format=json
- Spec: https://kolwrite-docs.pages.dev/openapi.json. Guide: https://kolwrite-docs.pages.dev/agents.md
2. When to use which call
| You want | Call |
|---|---|
| A transcript of a file, with word timings and speakers | upload session, then POST /api/v1/jobs (type: transcription), then GET /api/v1/jobs/{job_id}/export?format=json |
| SRT or VTT subtitles | GET /api/v1/jobs/{job_id}/export?format=srt or format=vtt |
| Subtitles in another language | options.target_language on the job, then export |
| Plain text | export?format=text |
| Word or PDF | export?format=docx or format=pdf |
| The transcript after people corrected it in the app | GET /api/v1/workspace-files/{workspace_file_id}/transcript?format=json (the job export includes the same corrections) |
| Only transcripts a person marked as reviewed | GET /api/v1/workspace-files/{workspace_file_id}/transcript?require_reviewed=true, or poll GET /api/v1/transcript-reviews?since=... |
| A call when a job finishes or a transcript is reviewed | POST /api/v1/webhook-endpoints (scope webhooks:manage); verify KolWrite-Signature |
| Text for a short voice clip, no job | POST /api/v1/ai/openai/audio/transcriptions |
| Chat, responses, embeddings | /api/v1/ai/openai/* (OpenAI-compatible endpoints) |
| The saved, versioned transcript | GET /api/v1/jobs/{job_id}/artifacts |
| The credit balance | GET /api/v1/billing/balance |
| A public link to a transcript | POST /api/v1/shares |
| Which model profiles exist | GET /api/v1/models |
3. Transcribe a file in Python
import json, mimetypes, os, time
import requests
BASE = "https://api-prod.kolwrite.com"
TOKEN = os.environ["KOLWRITE_TOKEN"]
def call(method, path, **kw):
headers = {"Authorization": f"Bearer {TOKEN}", **kw.pop("headers", {})}
r = requests.request(method, BASE + path, headers=headers, timeout=120, **kw)
r.raise_for_status()
return r
def transcribe(path, profile="oracle", language="auto"):
name, size = os.path.basename(path), os.path.getsize(path)
ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
session = call("POST", "/api/v1/media/upload-session",
json={"filename": name, "file_size_bytes": size,
"content_type": ctype}).json()["data"]
with open(path, "rb") as f:
requests.put(session["upload_url"], data=f, headers=session["headers"],
timeout=3600).raise_for_status()
media = call("POST", "/api/v1/media/complete",
json={"finalize_token": session["finalize_token"]}).json()["data"]
job = call("POST", "/api/v1/jobs",
headers={"Idempotency-Key": f"{name}-{size}-{profile}-{language}"},
json={"type": "transcription",
"input": {"type": "media_ref", "media_id": media["media_id"]},
"profile": profile,
"options": {"language": language,
"diarization": {"mode": "regular"}}}).json()["data"]
while True:
status = call("GET", f"/api/v1/jobs/{job['job_id']}").json()["data"]["status"]
if status in ("succeeded", "failed", "cancelled"):
break
time.sleep(5)
if status != "succeeded":
raise RuntimeError(f"job {job['job_id']} {status}")
export = call("GET", f"/api/v1/jobs/{job['job_id']}/export",
params={"format": "json"}).json()
return job["job_id"], json.loads(export["data"]) # data is a JSON string
job_id, transcript = transcribe("interview.wav")
for seg in transcript["segments"]:
print(f"{seg['start']:.2f}-{seg['end']:.2f} {seg.get('speaker', '')} {seg['text']}")
Large files are uploaded in parts: the session then returns data.upload_url as null and a URL for each part in data.multipart_part_urls (see the quickstart).
4. Use the timings
The JSON export has segments, each with start and end in seconds, text, a speaker when diarization ran, and words (text, start, end). Let the agent choose segments by index and read the times from the transcript; never let a model type timestamps.
import subprocess
keep = [s for s in transcript["segments"] if "pricing" in s["text"].lower()]
for i, seg in enumerate(keep):
subprocess.run(["ffmpeg", "-y", "-i", "talk.mp4", "-ss", str(seg["start"]),
"-to", str(seg["end"]), f"clip{i}.mp4"], check=True)
Subtitles come straight from the API. include_speakers=false leaves the speaker names out, and max_chars_per_entry sets the length of each subtitle entry:
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" -o talk.srt \
"https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=false&max_chars_per_entry=42"
SRT and VTT downloads are free on every plan.
5. Rules for agents
- Send an
Idempotency-Keywhen creating a job, so a retry never starts a second one. - Retry
429,502,503and504with exponential backoff; on429wait forRetry-After. Do not retry401,403or validation errors. See errors. - Read
detail.code, not the message text. - A job reserves credits when it is created and settles when it finishes; check
GET /api/v1/billing/balancebefore a large batch. - The OpenAPI file is the contract: every operation lists its required scope in
x-required-scope.
Questions
How do I make SRT subtitles from a video with an AI agent?
Upload the file, create a transcription job, wait for succeeded, then call the export endpoint with format=srt.
Can Claude Code or Codex call the KolWrite API?
Yes. They call it over HTTPS with a personal access token from an environment variable. There is no SDK or MCP server to install.
How does an agent get word timestamps?
Export the job as JSON. Each segment carries words with start and end in seconds.