API reference

Base URL

All public API endpoints use HTTPS and the following production origin.

https://capslane.com

Authentication

Send a workspace key in the x-api-key request header. Keep production keys in server-side environment variables.

A dashboard cookie does not authenticate public API calls. Examples below use Bash syntax; in PowerShell, use curl.exe with $env:CAPSLANE_API_KEY.

Read the Markdown reference or use OpenAPI JSON for request and response schemas.

GET /v1/account returns workspace as a string containing the workspace name, plan as a string, and monthlyLimit as an integer. It reserves no transcript unit. Current SDKs do not expose an account method; call HTTP directly.

curl 'https://capslane.com/v1/account' \
  -H "x-api-key: $CAPSLANE_API_KEY"

GET /v1/transcript returns HTTP 200 with content as a segment array by default, or a string when text=true. An accepted generation returns HTTP 202 with jobId, status and requestId, without content. Both SDK transcript methods return these same response bodies. Read content first, then retain jobId if generation was accepted.

Query parameters

Capslane checks the cache before applying the requested mode. A cached result can come from native captions or audio generation in any mode. Check source and cached in the response; mode controls what happens on a cache miss.

lang is a preference, not a translation request. Inspect lang for the selected language and availableLangs for the tracks reported by the source.

Immediate responses support text=true for one string, or timestamped segments by default. Segment offsets and durations are milliseconds. chunkSize groups whole segments using a character budget from 50 to 10,000; an individual source segment can exceed that budget. text=true takes precedence over chunkSize.

curl --fail-with-body --get "https://capslane.com/v1/transcript" \
  --header "x-api-key: $CAPSLANE_API_KEY" \
  --data-urlencode "url=dQw4w9WgXcQ" \
  --data-urlencode "mode=native"

200 response

A native, generated or cached transcript is ready. Offsets and durations are expressed in milliseconds.

{
  "content": [
    {
      "text": "Example segment.",
      "offset": 8150,
      "duration": 1200,
      "lang": "en"
    }
  ],
  "lang": "en",
  "availableLangs": [
    "en"
  ],
  "source": "native",
  "cached": false,
  "requestId": "req_example"
}

202 response

A generation job was accepted. Use jobId to construct the status URL; no separate job URL is returned. Progress is optional.

{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "requestId": "req_example"
}

Poll GET /v1/transcript/{jobId} with a key from the same workspace. HTTP 200 can contain a pending or failed job. Wait for content, stop on failed, cancelled or completed without content, and set a deadline. Progress is optional. Keep the accepted job ID to resume waiting without submitting another transcript request.

Set CAPSLANE_JOB_ID to the accepted ID. This command checks once.

curl --fail-with-body "https://capslane.com/v1/transcript/$CAPSLANE_JOB_ID" \
  --header "x-api-key: $CAPSLANE_API_KEY"

Job states

queued, downloading, processing, persisting, completed, failed or cancelled.

Completed job, HTTP 200

{
  "content": [
    {
      "text": "Example segment.",
      "offset": 8150,
      "duration": 1200,
      "lang": "en"
    }
  ],
  "lang": "en",
  "availableLangs": [
    "en"
  ],
  "source": "generated",
  "cached": true,
  "requestId": "req_example",
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed"
}

The public job endpoint returns canonical timestamped segments when complete. It does not reapply text or chunkSize from the initial request. Join the returned segment text locally if you need one string. A completed response also has jobId, so use content to recognize a ready transcript.

Failed job, HTTP 200

{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "upstream_unavailable",
  "requestId": "req_example"
}

Stopping a client request or reaching a client timeout does not cancel an accepted server job. Resume with its job ID. JavaScript SDK 0.1.3 bounds both waits and in-flight reads within the polling deadline. Python checks its polling deadline between iterations. Each HTTP request also has its own timeout.

Stop polling immediately if status is completed and content is absent. The stored result may have expired; further status checks will not restore it. Retain the job ID for investigation.

Errors

API request errors use the following envelope. Job failures can carry an error code without a message. Network and proxy failures may not return JSON.

{
  "error": "invalid_video_id",
  "message": "The YouTube video ID is invalid",
  "requestId": "req_example"
}

These are common errors. Upstream services can return additional codes, such as video_unavailable. SDK processing_timeout describes a local wait timeout and does not prove a server job failed.

For a short rate limit, HTTP 429 uses request_failed with a Retry-After header. Monthly request and generated-minute limits require an allowance change or monthly reset. A concurrency limit can clear when the active generation finishes. Retry temporary upstream or capacity failures with bounded backoff; when polling, retry the same job ID.

Limits

A transcript request reserves one monthly unit before extraction and cache lookup. A cache hit uses one unit, and a later extraction failure can still consume that unit. Repeating the initial request can consume another unit. Job status and account checks do not reserve transcript units. A request rejected for an exhausted monthly allowance adds no unit.

Transcript submission and job status endpoints each allow 120 requests per minute per client IP. Account checks allow 60. Free workspaces include 50 transcript requests and 15 generated minutes per month, with one active generation at a time. Check the pricing page for current plan allowances.

See pricing for current plan allowances.