Quickstart

Automate everything you do in the KolWrite app — upload a file, transcribe it with full options, export the transcript, and share it — using a personal access token.

Base URL: https://api.kolwrite.com

1. Create a token

In the KolWrite app go to Settings → Account → API access → Create token, and pick the scopes you need (this walkthrough uses files:write, jobs:write, jobs:read, transcripts:read). The secret is shown once — store it safely, then send it on every request:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.kolwrite.com/api/v1/billing/balance

2. Upload a file

Create an upload session, PUT the bytes to the presigned URL, then finalize:

# a. create the session
curl -X POST https://api.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "interview.wav", "content_type": "audio/wav"}'
# → data.upload_url, data.media_id, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "MEDIA_ID", "finalize_token": "FINALIZE_TOKEN"}'

3. Transcribe it

Create a job. The profile picks the model tier (oracle, oracle-mini, oracle-pro, oracle-max — list them at GET /api/v1/models); options carries everything the app's Analyze dialog exposes. Use an Idempotency-Key so retries never double-submit:

curl -X POST https://api.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"

Caption burn works the same way with type "caption_burn" and an options.caption_burn style block — see the reference.

4. Poll until done

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting

5. Export the transcript

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

Formats: text, json, srt, vtt. Durable transcript artifacts with version history are available under GET /api/v1/jobs/JOB_ID/artifacts and GET /api/v1/artifacts/{artifact_id} with the transcripts:read scope.

6. Optional: share it

With the shares:write scope:

curl -X POST https://api.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url