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-prod.kolwrite.com
1. Create a token
API access is self-serve: once your account has bought credits, turn it on in Settings → Account → API access. Calls spend your credits.
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-prod.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
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api-prod.kolwrite.com/api/v1/media/upload-session \
-H "Authorization: Bearer $KOLWRITE_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, 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-prod.kolwrite.com/api/v1/media/complete \
-H "Authorization: Bearer $KOLWRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id
Large files are uploaded in parts. The session then returns a null data.upload_url and one URL per part in data.multipart_part_urls: PUT each part, keep the ETag header of each response, and send them to the finalize call as uploaded_parts, a list of objects with part_number and etag.
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-prod.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-prod.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-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"
Formats: text, json, srt, vtt, docx, pdf. The export is the transcript as it is now: corrections people make in the KolWrite editor are included as soon as they are saved, with no extra step.
To read a file's current transcript by its workspace file ID (the same text people see in the app), use GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json with the transcripts:read scope. Its X-Transcript-Version-Id and X-Transcript-Revision headers change whenever the transcript does, so a poller can tell when there is something new. Stored transcript versions are under GET /api/v1/jobs/JOB_ID/artifacts and GET /api/v1/artifacts/{artifact_id}; a stored version is a fixed snapshot and does not include later edits.
To pick up only transcripts a person has approved, have reviewers press "Mark as reviewed" in the editor. The transcript call then sends X-Transcript-Review-Status: reviewed until the next edit, and require_reviewed=true makes it answer 409 transcript_not_reviewed otherwise. GET /api/v1/transcript-reviews?since=... lists files reviewed since your last poll. Or skip polling: add a webhook with POST /api/v1/webhook-endpoints (scope webhooks:manage) for transcript.reviewed, job.completed, job.failed, upload.completed or upload.failed, and check each request's KolWrite-Signature header (HMAC-SHA256 of <t>.<raw body> with the endpoint secret).
SRT and VTT downloads are free on every plan.
6. Optional: share it
With the shares:write scope:
curl -X POST https://api-prod.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