CaptionPass API v1

Integrations

Machine-readable contract and importable collections for CI pipelines and API clients.

• OpenAPI 3 — https://www.captionpass.com/docs/api/openapi.json (routes, errors, multipart process schema).
• Postman — import CaptionPass-v1.postman_collection.json and environment template. Set apiKey to your cp_live_… secret.
• Examples — curl, Node, and Python under repo examples/api/ (GitHub).

Import in Postman: Import → Link paste the collection URL, then import the environment and select it before sending requests.

Authentication & base URL

Send your secret on every request (TLS required in production). Never put keys in query strings, logs, or browser bundles.

Authorization: Bearer cp_live_...

Key management uses your logged-in session at Account (cookies). Integrations use Bearer only.

https://www.captionpass.com/api/v1/...

Quotas & rate limits

• Burst: ~45 requests per rolling 60s per API key → 429 rate_limited.
• Export validate/test also counts toward your daily v1 success pool (1–2 per request by mode). A separate hourly burst (default 60/hour) applies to all export-template operations.
• No Retry-After header — back off exponentially.

Scopes & route map

Legacy keys default to process:write only. Management routes need explicit scopes and matching entitlements. 403 may include details.missingScope or details.missingFeature.

POST /api/v1/process

POST only. Multipart multipart/form-data.

• file — required (SRT, VTT, SBV, ASS, TTML, or JSON IR).
• preset — optional, default youtube.
• fixProfile — optional: warn-only, layout-preserve-breaks, auto-split-sentences, auto-split-cps.

• Max file ~2048 KB (2 MiB). Declared Content-Length over ~4.25 MiB → 400 payload_too_large before read.
• Not for browser CORS — call from your backend only.

Presets

curl -sS -X POST "https://www.captionpass.com/api/v1/process" \
  -H "Authorization: Bearer $CAPTIONPASS_API_KEY" \
  -F "file=@./captions.srt" \
  -F "preset=youtube"

Success (200)

JSON: report, output, optional dual-delivery fields (aidedOutput, suggestions, …), and remainingApiRunsToday.

GET /api/v1/me

Scope account:read. Returns account profile: userKey, tier, features[], quotas, email.

curl -sS "https://www.captionpass.com/api/v1/me" \
  -H "Authorization: Bearer $CAPTIONPASS_API_KEY"

GET /api/v1/usage

Scope usage:read. Daily cap, today's count, remainingToday, and masked API key list.

curl -sS "https://www.captionpass.com/api/v1/usage" \
  -H "Authorization: Bearer $CAPTIONPASS_API_KEY"

API keys CRUD

• GET /api/v1/api-keys — keys:read; masked prefixes only.
• POST /api/v1/api-keys — keys:write; body { "name", "scopes": ["process:write", ...] }; returns one-time secret.
• DELETE /api/v1/api-keys/{keyId} — revoke.

Webhooks (Pro)

Scopes webhooks:read / webhooks:write. Requires PRO_WORKSPACE.

• GET /api/v1/webhook — config + masked secret.
• PUT /api/v1/webhook — HTTPS URL required; optional rotateSecret.

Dashboard export-complete webhooks (HMAC X-CaptionPass-Signature) are documented below — same secret concept as Account → Export webhooks.

Custom export scripts (CPES)

Pro ADVANCED_EXPORTS. JavaScript must define exportTimeline(cues, ctx). See Custom exports (CPES) for the full language reference.

mode: validate | test | both

• validate — syntax + QuickJS dry-run on sample cues. Charges 1 successful v1 run on pass.
• test — full run on project IR. Requires projectId (ready project). Charges 1 on pass.
• both — validate then test on project. Charges 2 on full success (validate failure does not charge test).
• Each success response includes remainingApiRunsToday (same daily pool as POST /api/v1/process).

curl -sS -X POST "https://www.captionpass.com/api/v1/export-templates/validate" \
  -H "Authorization: Bearer $CAPTIONPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scriptSource":"function exportTimeline(cues,ctx){ ... }","mode":"both","projectId":"YOUR-PROJECT-UUID"}'

Error envelope

{ "error": { "code": "unauthorized", "message": "…", "details": { } } }

Common process diagnostic codes

Do not use POST /api/process

Export-complete webhooks (dashboard)

Configure under Account → Export webhooks. On each successful export, CaptionPass POSTs JSON with X-CaptionPass-Signature (HMAC-SHA256). Event export_complete includes projectId and artifact list.

{
  "event": "export_complete",
  "receipt": {
    "version": 1,
    "kind": "single_export",
    "projectId": "…",
    "irRevision": 3,
    "artifacts": [{ "preset": "youtube", "exportId": "…", "filename": "…" }]
  }
}

Request & response examples

Illustrative JSON bodies. Field sets may include additional keys on success; treat unknown fields as optional.

POST /api/v1/process — 200

{
  "report": { "diagnostics": [], "summary": "…" },
  "output": "1\n00:00:01,000 --> 00:00:04,000\n…",
  "aidedOutput": "1\n00:00:01,000 --> 00:00:04,000\n…",
  "aidedSameAsDelivery": false,
  "suggestions": [{ "code": "reading_speed_high", "cueIndex": 2 }],
  "deliveryStatus": "will_adapt",
  "aidedStatus": "ready",
  "remainingApiRunsToday": 19
}

GET /api/v1/me — 200

{
  "userKey": "usr_…",
  "tier": "free_plus",
  "email": "you@example.com",
  "features": ["API_V1", "API_KEYS"],
  "quotas": { "v1DailySuccessCap": 10, "remainingToday": 7 }
}

GET /api/v1/usage — 200

{
  "cap": 10,
  "usedToday": 3,
  "remainingToday": 7,
  "keys": [{ "keyId": "…", "prefix": "cp_live_abcd", "name": "CI" }]
}

401 unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

403 forbidden (missing scope)

{
  "error": {
    "code": "forbidden",
    "message": "Missing scope.",
    "details": { "missingScope": "account:read" }
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily API conversion limit reached. Try again tomorrow."
  }
}

Export webhook verification

When Account → Export webhooks is configured, CaptionPass POSTs to your HTTPS endpoint on each successful export. Verify X-CaptionPass-Signature before trusting the body.

Payload

{
  "event": "export_complete",
  "receipt": {
    "version": 1,
    "kind": "single_export",
    "projectId": "a0000000-0000-4000-8000-000000000001",
    "irRevision": 3,
    "artifacts": [
      { "preset": "youtube", "exportId": "delivery", "filename": "youtube-delivery.srt" }
    ]
  }
}

Node.js verification

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyCaptionPassWebhook(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const got = String(signatureHeader || "").replace(/^sha256=/i, "");
  if (got.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(got, "utf8"), Buffer.from(expected, "utf8"));
}

• Read the raw request body as bytes/string before JSON parse — the HMAC is over exact bytes.
• Respond 2xx quickly; retries are best-effort. Use receipt.irRevision for idempotency.
• Configure URL and rotate secret under Dashboard → Account.

Versioning & stability

Paths are versioned (/api/v1/…). Breaking changes will ship under /api/v2 when needed. Non-breaking additions (new optional JSON fields, new presets) may appear without a version bump — clients should ignore unknown fields.

• Rate limits: no Retry-After header; use exponential backoff on 429.
• Success metering: only HTTP 200 responses decrement remainingApiRunsToday (UTC day).