The machine-readable OpenAPI 3.1 contract is available at:
https://api.clipsubtitles.com/openapi.json
The production API base is:
https://api.clipsubtitles.com
Send an OAuth 2.1 bearer token in the Authorization header. Use captions:read for read operations and captions:write for mutations. Browser sessions and agent grants are workspace-scoped. Never place bearer tokens in URLs, logs or screenshots.
/v1/projects — create and list projects;
/v1/projects/{projectId} — read, update or delete one project;
/v1/projects/{projectId}/captions — generate and edit captions;
upload and direct-upload targets — safely attach source media;
/v1/projects/{projectId}/previews — request a free short preview;
render quotes and renders — quote first, approve second;
/v1/tasks/{taskId} — poll or cancel durable work;
/v1/exports and export content routes — list metadata and download finished files;
/v1/workspace — read or update workspace settings and retention;
/v1/credits and /v1/credits/ledger — inspect balance and credit events; and
/v1/connections — inspect and revoke agent connections.
The OpenAPI document is the source of truth for request and response schemas.
Import, caption generation, preview and final rendering are durable tasks. A successful request may mean the task was accepted, not that processing has finished. Poll the returned task until it reaches a terminal state. Use bounded backoff rather than polling continuously.
Send an Idempotency-Key where the OpenAPI operation supports it. Reusing the same key with the same operation returns the original result. Reusing it for conflicting input returns an error. Project edits use optimistic version checks; on a version conflict, fetch the latest project before retrying.
Public errors are bounded and may include an errorRef. Store the status code, request time, operation name and errorRef, but do not log transcript text, tokens or signed URLs. Send those safe details to [email protected] when human help is needed.
