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.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.

1. Give the agent a token

• API access is enabled per account; without it, creating or using a token is refused.
• 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.

Paste this into AGENTS.md, CLAUDE.md or .cursorrules:

## KolWrite platform API
- Base URL https://api.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

3. Transcribe a file in Python

import json, mimetypes, os, time
import requests

BASE = "https://api.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.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=false&max_chars_per_entry=42"

SRT and VTT downloads need a Plus plan or higher. Other plans get HTTP 403 with the code subtitle_export_requires_plus; JSON and text exports are not affected.

5. Rules for agents

• Send an Idempotency-Key when creating a job, so a retry never starts a second one.
• Retry 429, 502, 503 and 504 with exponential backoff; on 429 wait for Retry-After. Do not retry 401, 403 or 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/balance before 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. Subtitles need a Plus plan or higher.

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.

Markdown version of this page