KolWrite API Documentation

Authentication

All API requests must be authenticated using your unique API key. Include it in the request headers:

x-api-key: YOUR_API_KEY

You can generate and manage your API keys in the KolWrite Console after creating an account.

Quickstart

Get started quickly with these basic examples.

1. Start Transcription

Send a POST request to the `/transcribe` endpoint with the URL of the audio file you want to transcribe.

Request:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Response:

The API returns a `jobId` which you'll use to retrieve the transcription results.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Get Transcription Result

Send a GET request to the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Request:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Response (Example):

Once the job status is COMPLETED, the response will include the transcription details.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Models & usage credits

Model usage is metered in usage credits per second with no minimum charge. Checkout, receipts, and tax documents show the real payment currency used for purchase.

1 credit is the API billing unit previously displayed as $1.00 in the API console.

Eligible Israeli billing accounts purchase usage credits in ILS at a net price of ILS 3.60 per credit before VAT. Checkout shows the usage credits, net amount, VAT, and final ILS total before payment. Other accounts purchase usage credits in USD at USD 1.20 per credit unless separate order terms apply.

Add-ons: Regular speaker diarization and standard channel separation are included. Pro Speaker Diarization adds 0.20 credits per audio hour. overlap channel separation is billed at the selected model rate for the greater of the recording duration or the total detected speech time across its physical channels; neither channel mode adds a diarization surcharge. Oracle Mini automatically enables timestamp alignment when speaker diarization or channel separation is selected.

API Endpoints

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Submits an audio file for asynchronous transcription with optional speaker diarization.

Request Body Parameters

Example Request (with diarization):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Response:

Returns an object containing the `jobId` for the submitted transcription task.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Retrieves the status and result of a specific transcription job.

Path Parameters

Response Body

Example Response (JSON Output with Speaker Diarization):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Speaker Diarization

Speaker diarization is the process of identifying and separating different speakers in an audio recording. When enabled, KolWrite will analyze the audio to detect speaker changes and label each segment accordingly.

Speaker diarization and channel separation are available with every listed model. Oracle Mini automatically enables timestamp alignment whenever a speaker mode is selected.

How to Enable Diarization

To enable speaker diarization, set the include_diarization parameter to true in your transcription request:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Speaker Count Optimization

For best results, specify the expected number of speakers using the num_speakers parameter. If you don't know the exact number, you can:

• Omit the parameter (system will auto-detect)
• Provide an estimated range by setting it to your best guess

Pro Diarization

For higher accuracy in speaker identification, especially in challenging acoustics, you can enable Pro Diarization. This feature costs an additional 0.20 credits per audio hour.

To use it, set the pro_diarization parameter to true. This parameter can be used in conjunction with include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Channel Speaker Separation

Channel separation transcribes each physical audio track independently and labels returned segments and words with their physical channel and speaker. It requires a two-to-eight-channel audio_url and cannot be combined with regular or Pro diarization. Oracle Mini automatically enables timestamp alignment for either channel mode.

Use standard when speakers take turns; it bills one selected-model audio rate. Use overlap when speakers can overlap; it bills the selected-model rate for the greater of the recording duration or the total detected speech time across its physical channels.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Completion Webhooks

Set webhook_url to receive transcription.completed and transcription.failed events. Delivery failures are retried, but clients should continue to support GET /transcribe/{jobId} as the source of truth.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Every delivery includes X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id, and X-KolWrite-Timestamp. Delivery is at least once; retries reuse the same delivery ID, so deduplicate events using X-KolWrite-Delivery-Id. When a secret is configured, compute HMAC-SHA256 over timestamp + "." + raw_request_body and compare it with X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

For output_format: "json", the webhook result field is a JSON object. TXT and SRT results are delivered as strings.

Large results may set result_omitted to true; fetch the complete result from GET /transcribe/{jobId}. Failed events include an error field.

Output Format with Diarization

When diarization is enabled, each segment in the JSON output will include a speaker field identifying the speaker (e.g., "Speaker 1", "Speaker 2", etc.).

Output Formats

JSON Format

Detailed output with segments, timestamps, and optional word-level data.

TXT Format

Plain text transcription with speaker labels (when diarization is enabled).

SRT Format

SubRip subtitle format with timestamps, compatible with video players and subtitle editors.

Service Status

See the public KolWrite API status page for live availability, uptime history, and service-level incidents.

GET /health requires no API key and returns the current API, job-intake, and transcription-processing state. A 200 response means the service is operational or degraded; a 503 response means the current state is unknown or unavailable. Both responses include JSON status details.

GET /health/history?period=24h returns compact availability history. Supported periods are 24h, 7d, and 30d.

Status Codes