---
title: "Developer quickstart: REST API"
description: "Discover the typed REST contract, authorization model, durable tasks and render approval boundary."
url: https://help.clipsubtitles.com/en/articles/7-developer-quickstart-rest-api
collection: "Developer API and MCP"
updated: 2026-09-02
language: en
---

# Developer quickstart: REST API

Discover the typed REST contract, authorization model, durable tasks and render approval boundary.

### Developer quickstart: REST API

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`

### Authentication

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.

### Main resource groups

-   `/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.

### Task model

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.

### Idempotency and conflicts

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.

### Errors and support

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 `support@clipsubtitles.com` when human help is needed.