Typecut API reference

List projects

Returns the projects the authenticated API key can access. Account-level keys see all projects in the account; workspace-scoped keys see only projects in their workspace. Cursor-paginated (created_at DESC, id DESC).

Parameters

Response — 200

200 A page of projects.400 Invalid query parameters.401 Missing or invalid API key.

Create a project

Create a new project. Mode-discriminated by `mode`: - `templates` — runs the full plan → scaffold → generate pipeline from a template + a topic (`prompt`) or your own `script` (markdown-structured supported). The main path. - `blank` — an empty project with one chapter, no planning; edit it via later API calls. For `templates`, call GET /v1/projects/requirements first to learn the required inputs (and preview a script's parsed structure).

Request body

Response — 201

201 Project created.400 Invalid request body.401 Missing or invalid API key.402 Plan limit reached (free tier project cap, lapsed subscription, etc).403 API key cannot create projects in the requested workspace.

List media assets

Returns the media library assets the API key can access (confirmed, excluding scene thumbnails). RLS-scoped to the account; workspace-scoped keys see only their workspace. Cursor-paginated (created_at DESC, id DESC). Optional `project_id` filter.

Parameters

Response — 200

200 A page of media assets.400 Invalid query parameters.401 Missing or invalid API key.

Add media to the library

Record an already-hosted asset URL into the project media library. This is for URLs that are already reachable (e.g. your own hosted file); it does not upload a file. Rate-limited per account.

Request body

Response — 201

201 Media asset recorded.400 Invalid request body.401 Missing or invalid API key.403 project_id is outside the key's workspace scope.404 project_id not found for this account.429 Rate limit exceeded.

Get a project

Fetch one project by id. Returns 404 (not 403) when the project exists but is not accessible by the API key — so callers cannot probe for existence.

Parameters

Response — 200

200 Project found.401 Missing or invalid API key.404 Project not found or not accessible.

Get a project generation trace

A token-light audit of how a project was planned and generated — what template resolved, whether it drove the plan, the pacing decision, per-scene/model summaries, and LLM step summaries. Compact by default; opt into detail with ?include=raw (full structure_config/prompt_config/catalog + per-element model list) and/or ?include=prompts (full LLM prompt blobs). 404 (not 403) when not accessible.

Parameters

Response — 200

200 The project trace digest.401 Missing or invalid API key.404 Project not found or not accessible.

List workspaces

Returns the workspaces the API key can access. Account-level keys see all workspaces; workspace-scoped keys see only the one they are scoped to. Cursor-paginated.

Parameters

Response — 200

200 A page of workspaces.400 Invalid query parameters.401 Missing or invalid API key.

Get a workspace

Fetch one workspace by id. Returns 404 (not 403) when the workspace exists but is not accessible by the API key.

Parameters

Response — 200

200 Workspace found.401 Missing or invalid API key.404 Workspace not found or not accessible.

Search open & archival assets

Entity-grounded asset search across open / archival sources (Wikimedia Commons, NASA, ...). Resolves the query to a real-world entity, fans out to the sources, filters to commercially-usable licenses, and returns ranked candidates with license + provenance. Read-only; no asset is downloaded or stored by this call.

Request body

Response — 200

200 Ranked, license-cleared candidates.400 Invalid request body.401 Missing or invalid API key.502 Upstream discovery engine error.

Create a scene from raw NJS

Submit a raw NJS scene script directly — no prompt, no LLM. The script is transpiled server-side; any declared gen elements (gen:image / gen:video / gen:stock-image / gen:stock-video / gen:html) resolve asynchronously. Returns the scene id and a public `share_url` that renders the scene live as those elements resolve. Intended for agents that already produce NJS (see the NJS reference at njs.typecut.ai). The public viewer and its polling endpoint (`GET /api/share/{token}`) need no authentication.

Request body

Response — 201

201 Scene created; gen elements (if any) are resolving asynchronously.400 Invalid request body.401 Missing or invalid API key.402 Plan limit reached.403 API key cannot create scenes in the requested workspace.422 NJS failed to transpile — diagnostics are in the error `detail`.

Get render status

Poll the latest render job for a project: phase, per-scene progress, stitch progress, and the final MP4 URL (`render_url` / `job.output_url`) once completed.

Parameters

Response — 200

200 Current render status.404 Project not found or not accessible.

Render a project to video

Trigger a full project video render. Validates readiness first: every chapter must have TTS audio and every scene must have visual content. On readiness failure the 422 response carries machine-readable `blockers` (chapter ids missing audio, scene ids missing visuals) so callers can resolve them programmatically. Credits are deducted up front and refunded automatically if the render cannot be queued. Poll GET /projects/{id}/render for progress and the final MP4 URL.

Parameters

Request body

Response — 202

202 Render queued.402 Insufficient credits.404 Project not found or not accessible.409 Project is already rendering.422 Project not ready to render — `blockers` lists the chapters missing audio and scenes missing visuals.503 Render queue unavailable (credits were refunded).

Get resolution status

What's resolved vs unresolved in a project, and the estimated credits to resolve the rest. A scene is resolved once it has renderable content; voice-over is tracked per chapter. Read-only counterpart to POST /projects/{id}/resolve — the counts match the editor's readiness UI exactly (shared logic).

Parameters

Response — 200

200 Resolution status + cost quote.404 Project not found or not accessible.

Resolve (generate) unresolved work

Generate everything unresolved in a scope — its unresolved scenes (composition) plus voice-over. Mirrors the editor's "Generate everything" actions; each underlying generation charges and refunds itself. Scenes with nothing to generate from are skipped (`skipped_unresolvable`). Pass `dryRun:true` for the credit quote without firing anything (identical numbers to GET /projects/{id}/resolution).

Parameters

Request body

Response — 200

200 Dry-run quote — nothing was fired.202 Resolution started — generations were queued.400 Invalid scope (e.g. chapter scope without chapterId).403 Subscription inactive (past_due / unpaid).404 Project, chapter, or block not found.

List a value catalog

The discoverability layer: every value project creation/editing accepts by id or slug is listable here, straight from the live registries. Catalogs: `transitions` (scene transition slugs + render mode + default duration), `caption-styles` (caption style ids + preview clips), `voices` (TTS presets — system + your own), `music` (published music tracks + license info). Pass the returned slug/id values to the matching creation or editing fields.

Parameters

Response — 200

200 Catalog rows.404 Unknown catalog.

Attach media to a scene

Set a scene's background to an image or video URL. The first editor-mutation primitive on the API: it shares the editor's media-attach service, so the change appears live in any open editor (via Realtime, applied in place) and behaves identically to picking media in the UI. Scene ids are globally unique, so the flat path is unambiguous.

Parameters

Request body

Response — 200

200 Media attached; scene background updated.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.

Add an element to a scene

Append one element — motion design, an image, or a text box — to an existing composition. SPENDS CREDITS: the new line goes through the generate-composition raw-NJS path, which transpiles, persists, and dispatches a resolve job. Asynchronous; poll the scene. Contrast PATCH on the same path, which edits existing elements for free.

Parameters

Request body

Response — 202

202 Element accepted and generating.400 Invalid request body or parameters.401 Missing or invalid API key.402 Insufficient credits.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Edit elements in a scene

Element-level edits on a scene, expressed as patches against its NJS source. This is the same vocabulary and the same applier the editor canvas uses for a drag, resize, retime, recolour or restyle, so an API caller and a person on the canvas produce identical results. Read the scene first to get current line numbers. Spends no credits — an edit is a source rewrite plus a transpile, not a generation. Scene ids are globally unique, so the flat path is unambiguous.

Parameters

Request body

Response — 200

200 Patches applied; scene re-transpiled and persisted.400 Invalid request body, or no patch matched the source.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.409 Stale write: a line in expect_lines no longer matches, expected_version is behind, or the row changed while the edit was being transpiled. Nothing was written.422 The patched script failed to transpile.

Create a theme

Author a private theme owned by your account — a palette (colours keyed by role) and an optional type pairing. Reference the returned `slug` as `themeSlug` when creating a project. Only the safe design fields are settable here; image-generation routing and prompt directives are managed by the system.

Request body

Response — 201

201 The created theme.400 Invalid body.401 Missing or invalid API key.

Describe a scene's gen:html sub-compositions

Return the visual-unit map of every resolved gen:html sub-composition in a scene — the same "what's inside this composition" structure the editor canvas exposes on double-click, but read statically from the hosted blob (no browser). Each unit carries its id/label, whether it is a timed `.clip` layer, and its animation lanes (properties + times); engine fills also return the parsed window.__DATA__ (their editable surface) with confidence "partial". Read-only. Scene ids are globally unique, so the flat path is unambiguous.

Parameters

Response — 200

200 The scene's gen:html unit maps.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.

Edit a gen:html sub-composition's inner units

Apply deterministic, LLM-free edits to inner units of a resolved gen:html sub-composition: delete_unit removes the unit's element subtree; hide_unit hides it in place. The hosted blob is rewritten IMMUTABLY (a new copy is hosted and the scene's resolution swaps to it) — the previous URL is returned so the edit can be reverted. Unit keys come from GET …/genhtml.

Parameters

Request body

Response — 200

200 The edit result.400 Invalid body.404 Scene or composition not found.422 Edit could not be applied (e.g. unit not found in the blob).

Create a scene

Create a scene in a chapter. A prompt-only body makes a draft composition scene (generation pending); a `media_url` body makes a resolved "uploaded" scene with its background already set. Shares scene-crud-service with the Director chat.

Request body

Response — 201

201 Scene created.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Get a scene

Read one scene in full, including its NJS composition source and `composition_version`. Read a scene before rewriting it — patches address the source by line number.

Parameters

Response — 200

200 The scene.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Update a scene

Update a scene's own fields. To adjust one element inside the composition, prefer PATCH /scenes/{sceneId}/elements — it patches source lines instead of replacing the script.

Parameters

Request body

Response — 200

200 Scene updated.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Delete a scene

Soft-delete: the scene becomes a restorable tombstone rather than being removed, so other clients reconcile the removal and the change can be undone.

Parameters

Response — 200

200 Scene soft-deleted.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Get single-scene render status

Poll for the rendered clip. The URL lands on the scene once the job completes.

Parameters

Response — 200

200 Render status.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Render a single scene

Render one scene to a standalone MP4 — no project stitch, no audio bed. SPENDS CREDITS. Shares render-scene-service with the Studio render button. Poll with GET on the same path.

Parameters

Request body

Response — 202

202 Render queued.400 Invalid request body or parameters.401 Missing or invalid API key.402 Insufficient credits.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Get the storyboard

The structural map of a project: chapters, script blocks, and the scenes anchored to each block, with voice-over status and durations. The orientation call — read this before editing so you address real ids. Scene detail is deliberately excluded; use GET /scenes/{id}.

Parameters

Response — 200

200 The storyboard.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Inspect creation requirements

Dry-run of the template-driven creation resolver: given a template and a workspace, reports what the workspace presets would prefill, what is still required, and what the template offers as optional — creating nothing. Same resolver POST /projects runs, so an agent can ask exactly the right questions before spending anything.

Parameters

Response — 200

200 Resolved requirements.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Create a chapter

Create a chapter. Pair with POST /chapters/{chapterId}/blocks and POST /scenes to build a project's structure headlessly, using the same services the Director chat uses.

Parameters

Request body

Response — 201

201 Chapter created.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Bulk-generate scenes

Start bulk scene generation on a planned draft — the "Generate scenes" button, headless. Valid only from status='draft' with a script. SPENDS CREDITS: the bulk estimate is deducted upfront, with refund-on-failure.

Parameters

Response — 200

200 Bulk generation started.400 Invalid request body or parameters.401 Missing or invalid API key.402 Insufficient credits.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Create a share link

Mint a public share link. Same gate as the editor Share button: the project must be fully resolved — no unresolved scenes, no chapter missing voice-over — before a link is minted.

Parameters

Response — 200

200 Share link.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.409 Conflict with a concurrent change.

Add a script block

Add a block to the chapter's script. Blocks live in chapters.script_blocks; narration blocks are what voice-over and scene anchors attach to.

Parameters

Request body

Response — 201

201 Block added.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Rewrite a script block

Replace a block's text. Timing derived from the OLD text — pauses, silence trims, scene anchors — is cleared, because offsets into replaced text would be meaningless. Re-anchor scenes afterwards if the block carried any.

Parameters

Request body

Response — 200

200 Block updated.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Reorder a chapter's scenes

Set the full scene order. The body must list EVERY non-deleted scene id in the chapter exactly once — full-order semantics, so a stale caller cannot silently interleave with a concurrent edit.

Parameters

Request body

Response — 200

200 New order applied.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Get the project theme

The project's visual identity: theme slug, colour roles, font roles, light/dark.

Parameters

Response — 200

200 The theme.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Switch or restyle the theme

Exactly one of `slug` (switch to an existing theme) or `restyle` (fork-on-edit). A restyle never mutates a shared preset: it copies the current theme into a private user theme with the patch applied and repoints the project at the fork. NOTE: themes are baked into each scene at generation time, so already-generated scenes keep their look until regenerated — the response repeats this in `note`.

Parameters

Request body

Response — 200

200 Theme switched or forked.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Get caption settings

The project-level caption default. Scene overrides live on the scene.

Parameters

Response — 200

200 Caption settings.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Set caption settings

Set any subset of the caption default. Unlike a theme change this is free and needs no regeneration — captions are a render overlay, so the change lands on the next render. `style` is a fine-tune partial, DEEP-merged over the existing one; pass null to clear it. Preset ids come from GET /catalogs/caption-styles.

Parameters

Request body

Response — 200

200 Updated caption settings.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

List liked shares

The staff "liked shares" collection — every share hearted on a /share/<token> page — as a flat list an ingestion client can enumerate without DB or browser access. STAFF ONLY: the key's account needs an admin role; other keys get 403. Shared collection, not per-account.

Response — 200

200 Liked shares, newest first.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.

Get the pricing catalog

Plans, credit packs, marketing-flagged features, and per-generation estimates, assembled from the DB. PUBLIC — no authentication, CORS-open and CDN-cached, because the marketing site fetches it cross-origin.

Response — 200

200 Pricing catalog.