API reference

The Typecut API is JSON over HTTPS. It is the same surface the editor uses, and every MCP tool forwards to it, so sign-in, validation, errors and credits behave the same everywhere. The pages in this section are generated from the live OpenAPI spec, which you can also load into Postman, Insomnia or a client generator.

Quick start

Create a key in Settings → API keys in the app (API keys need the Creator plan or higher), then list your projects:

curl https://app.typecut.ai/api/v1/projects?limit=2 \
  -H "Authorization: Bearer $TYPECUT_API_KEY"

{
  "data": [
    {
      "id": "8f0c2d7e-…",
      "name": "Bronze Age collapse",
      "status": "ready",
      "workspace_id": "c41b…",
      "aspect_ratio": "16:9",
      "editor_url": "https://app.typecut.ai/project/8f0c2d7e-…"
    }
  ],
  "next_cursor": "MjAyNi0xMC0yOFQx…"
}

Authentication

Send the key as a bearer token on every request.

GET /api/v1/projects HTTP/1.1
Host: app.typecut.ai
Authorization: Bearer tc_live_…

A key is either account-wide or scoped to one workspace. Use a workspace key for an agent that should only touch one brand or channel. A read-only key can call GET routes and nothing else. Rotate or revoke keys in Settings → API keys. An AI app you connected with OAuth is listed separately, under Settings → AI apps (MCP).

Conventions

• Errors. Every error has one shape, and the HTTP status gives the class:

  { "error": { "type": "invalid_request", "code": "invalid_query", "message": "limit: Number must be less than or equal to 100" } }

• Pagination. List routes take cursor and limit and return next_cursor, which is null on the last page.

• Credits. Operations that spend credits say so in their description. Price work first with POST /quotes, and reserve a quote's ceiling with POST /holds when several jobs run at once.

• Slow work. Generation and renders take minutes. They return an id at once; poll the matching GET route every 10 to 15 seconds.

• Rate limits. Per account, per minute: 600 reads, 120 writes, 60 status polls and 30 credit-spending calls. Over the limit you get 429 with retry_after_seconds.

Attribution

Every write records who made it: the key's name, plus the agent session you declare with the optional X-Typecut-Session: <id> and X-Typecut-Session-Label: <text> headers. People with the project open see the label as the agent's presence.

Endpoints