# Kaitoi REST API

> Public REST API for Kaitoi projects, files, node discovery, saved-project runs, and inline graph runs.

This file is the LLM-friendly entry point for Kaitoi REST API documentation.
Use the OpenAPI schema for exact request and response shapes.

## Guidance

- Authenticate with `Authorization: Bearer <api_key>`.
- Prefer Backend service keys for trusted backends, CLIs, desktop apps, workers, and scripts.
- Browser app keys are visible to end users and must be attached to a Developer App with exact allowed origins.
- Browser origin checks are not a substitute for narrow scopes, quotas, and server-side secrets.
- List cursors are opaque; never parse or construct them client-side.
- Errors use `{ "error": { "code", "message", "details" } }`.

## Primary References

- [Interactive API reference](https://api.studio.kaitoi.io/api/v1/docs): Human-friendly Scalar/OpenAPI docs.
- [OpenAPI JSON](https://api.studio.kaitoi.io/api/v1/openapi.json): Machine-readable API schema.
- [Postman collection](https://api.studio.kaitoi.io/api/v1/postman.json): Generated collection synced from OpenAPI.
- [Agent API docs](https://api.studio.kaitoi.io/api/v1/api-docs): Queryable generated docs for operation, schema, scope, route, and topic filters.
- [Full LLM reference](https://api.studio.kaitoi.io/api/v1/llms-full.txt): Markdown endpoint and schema summary.

## Overview

Kaitoi's REST API exposes a stable integration surface for projects, editable
project documents, graph inspection, node discovery, files, runs, and future
automation workflows.

**Authentication**

Send a programmatic API key as `Authorization: Bearer <api_key>`. Keys can be
scoped with endpoint-specific permissions such as `projects:read`,
`projects:write`, `templates:read`, `templates:run`, `runs:execute`,
`graphs:read`, `node_types:read`, `files:read`, and `files:write`.
Account credit balance reads require `account_credits:read`.

Kaitoi has two API key usage modes:

- **Backend service keys** are the default for trusted code: your backend,
  CLI tools, desktop apps, scripts, workers, and CI jobs. These keys are
  bearer secrets and should not be shipped in browser JavaScript.
- **Browser app keys** are for direct calls from frontend JavaScript. They
  must be attached to a Developer App with explicit allowed origins. The
  origin check lets browsers call the public REST API only from those
  registered origins, but it is not a substitute for keeping sensitive secrets
  on a trusted server. Browser keys are visible to end users, so prefer
  read-only or narrowly scoped permiss…

## Endpoints

### Account

- `GET /api/v1/account/credits` - Get account credits - Returns the authenticated user's current spendable account credit balance and PAYG/subscription breakdown. Requires the `account_credits:read` scope.

### Files

- `POST /api/v1/files` - Upload small file - Small-file convenience upload. This route is capped at 25 MB and is deprecated for developer-platform use; prefer POST /files/uploads.
- `POST /api/v1/files/uploads` - Create file upload session - Creates a direct-to-storage upload session. This endpoint does not upload the file bytes. Use the returned instructions as follows:

1. Send a separate PUT request to `upload.url` using `upload.method` and every header in `upload.headers`.…
- `DELETE /api/v1/files/uploads/{upload_id}` - Abort file upload - Aborts a pending upload session and releases its storage reservation.
- `POST /api/v1/files/uploads/{upload_id}/complete` - Complete file upload - Verifies that the bytes were uploaded to the signed URL returned by `Create file upload session`, then promotes the object to a durable REST API file record. This call is idempotent by `upload_id`; retrying after a successful completion re…
- `GET /api/v1/files/{file_id}` - Get file - Returns metadata for a REST API uploaded file owned by the authenticated account.
- `DELETE /api/v1/files/{file_id}` - Delete file - Deletes a completed REST API file owned by the authenticated account. Deletion is blocked while active saved projects reference the file, and fails closed when any plausible active project has not indexed file references yet.
- `GET /api/v1/files/{file_id}/download-url` - Get file download URL - Returns a short-lived signed URL for downloading a REST API uploaded file. The URL is time-limited and should not be stored permanently.

### Node Types

- `GET /api/v1/node-type-thumbnails/{node_type}` - Get node type thumbnail - Serves a short-lived signed node type thumbnail URL returned by the node type list and detail endpoints. The token in the URL authorizes only this thumbnail; do not send the REST API bearer token to this URL.
- `GET /api/v1/node-types` - List node types - Returns node types available to the authenticated user. Use this endpoint to discover compatible node identifiers before building automation against a graph.
- `GET /api/v1/node-types/{node_type}` - Get node type - Returns the public schema for one node type, including its exposed input and output pins. Node type paths are validated before lookup so user-node paths cannot traverse storage boundaries.

### Projects

- `POST /api/v1/projects` - Create project - Creates an empty saved project for the authenticated API key owner. Use Idempotency-Key so retries do not create duplicate projects.
- `GET /api/v1/projects` - List projects - Returns projects visible to the authenticated API key owner. Results are ordered by most recently updated project first and paginated with opaque keyset cursors.
- `GET /api/v1/projects/{project_id}` - Get project - Returns public metadata for a single project, including the current project version used by future write endpoints for optimistic concurrency.
- `PATCH /api/v1/projects/{project_id}` - Update project - Updates project display metadata and developer-provided external identifiers using optimistic concurrency.
- `DELETE /api/v1/projects/{project_id}` - Delete project - Deletes a project from the public REST API surface using optimistic concurrency. The project bundle and metadata are removed from project storage so the project no longer appears in Studio or public REST project lists.
- `GET /api/v1/projects/{project_id}/document` - Get project document - Returns the canonical editable project document. This shape is designed for developer round trips and uses input maps plus from/to connection tuples, unlike the read-only /graph inspection shape.
- `PUT /api/v1/projects/{project_id}/document` - Replace project document - Replaces the editable project document using optimistic concurrency. The public document graph is validated, translated into Studio's internal bundle shape, and saved as a normal project. Use Idempotency-Key so network retries can replay t…
- `PATCH /api/v1/projects/{project_id}/document` - Patch project document - Applies ordered semantic document operations atomically using optimistic concurrency. The resulting document is validated and saved through the same path as PUT /document. Use Idempotency-Key so network retries can replay the saved respons…
- `GET /api/v1/projects/{project_id}/graph` - Get project graph - Returns a sanitized graph snapshot for a project. Internal metadata, execution history, and private storage paths are intentionally omitted.
- `GET /api/v1/projects/{project_id}/graph/nodes/{node_id}` - Get project graph node - Returns one sanitized placed node from a project graph. Use fields=inputs,outputs for compact connection-pin discovery. Omit fields for the existing sanitized full graph-node shape.
- `PATCH /api/v1/projects/{project_id}/metadata` - Update project metadata - Updates project display metadata and developer-provided external identifiers using optimistic concurrency. Prefer this explicit route for metadata-only updates; PATCH /projects/{project_id} is kept as a compatibility alias.
- `GET /api/v1/projects/{project_id}/spend` - Get project spend - Returns actual billed credits from project-attributed ledger transactions. The response does not expose account balances, payment methods, or dollar amounts.

### Runs

- `POST /api/v1/runs` - Create run - Accepts a run request for either a saved project (`projectId`) or an inline transient graph (`graph`). The server validates file input references, target nodes, node types, and input pins; snapshots the selected graph source; creates an ac…
- `GET /api/v1/runs/{run_id}` - Get run - Returns a REST API run record owned by the authenticated API key owner.
- `POST /api/v1/runs/{run_id}/apply-to-project` - Apply run outputs to project - Persists outputs from a succeeded saved-project run back into that saved project. This is the public API equivalent of saving the server-owned run result state after execution; it does not accept client-supplied output values. The request…
- `POST /api/v1/runs/{run_id}/cancel` - Cancel run - Requests cancellation for a REST API run. Accepted or queued runs become terminal canceled immediately; running runs are marked cancelRequested for the execution layer to stop at the next safe point.
- `GET /api/v1/runs/{run_id}/events` - List run events - Returns persisted lifecycle, progress, and log events for a REST API run. Cursors are opaque and are only valid for the same run and API key owner that issued them.
- `GET /api/v1/runs/{run_id}/events/stream` - Stream run events - Streams the same persisted lifecycle, progress, and log events returned by the polling endpoint using Server-Sent Events. The SSE id is an opaque cursor and can be sent back as Last-Event-ID or as the cursor query parameter to resume the s…

### Storyboards

- `GET /api/v1/projects/{project_id}/storyboard` - Get project storyboard - Returns the project's current storyboard as a Kaitoi Storyboard Document v1. This is a read-only export of storyboard state.
- `PUT /api/v1/projects/{project_id}/storyboard` - Update project storyboard - Applies a Kaitoi Storyboard Document v1 to a saved project using optimistic concurrency. Supports replacing the current storyboard or appending imported scenes. Use Idempotency-Key so network retries can replay the saved response.
- `GET /api/v1/storyboards/schema/kaitoi-storyboard-document.v1` - Get storyboard document schema - Returns the canonical Kaitoi Storyboard Document v1 JSON Schema. This route is unauthenticated so public API clients can validate documents before sending them.
- `POST /api/v1/storyboards/to-timeline` - Convert storyboard document to timeline document - Converts a Kaitoi Storyboard Document v1 into a Kaitoi Timeline Document v1 without mutating any project. Storyboard shots become sequential timeline clips; URL, document, unresolved, and unsupported media references are skipped with warni…
- `POST /api/v1/storyboards/validate` - Validate storyboard document - Validates a Kaitoi Storyboard Document v1 against the same schema enforced by the backend.

### Templates

- `GET /api/v1/templates` - List templates - Returns user-owned templates visible to the authenticated API key owner. Use `hasEndpoint=true` to discover app-ready templates that already have at least one active endpoint. Use endpoint docs to inspect the external endpoint contract and…
- `GET /api/v1/templates/{template_id}` - Get template - Returns public metadata for one user-owned template, including active endpoint summaries when the template has app-ready endpoints.
- `GET /api/v1/templates/{template_id}/endpoints` - List template endpoints - Returns active external endpoints for a user-owned template. Endpoint API secrets are never returned; use the endpoint docs response to learn the required Authorization header shape.
- `GET /api/v1/templates/{template_id}/endpoints/{endpoint_id}/docs` - Get template endpoint docs - Returns docs for an active external endpoint on a user-owned template: authentication header shape, submit/status paths, and exposed input and output fields. This does not return endpoint API keys and does not run the endpoint.
- `POST /api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs` - Run template endpoint - Submits an owner-authenticated run for an active endpoint on a user-owned template. The API key user must own the template and endpoint, the key must have `templates:run`, file inputs must reference Public API fileIds, and execution may sp…
- `GET /api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs/{task_id}` - Get template endpoint run - Returns a template endpoint run owned by the authenticated API key owner. Polling requires `templates:run` because completed results are part of the execution contract.
- `GET /api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs/{task_id}/events/stream` - Stream template endpoint run events - Streams compact lifecycle and progress events for an owner-authenticated template endpoint run using Server-Sent Events. This endpoint requires `templates:run` because progress and completed results are part of the execution contract.

### Timelines

- `GET /api/v1/projects/{project_id}/timeline` - Get project timeline - Returns the project's current active timeline as a Kaitoi Timeline Document v1. This is a read-only export of timeline state.
- `PUT /api/v1/projects/{project_id}/timeline` - Update project timeline - Replaces a saved project's active timeline with a Kaitoi Timeline Document v1 using optimistic concurrency. Use Idempotency-Key so network retries can replay the saved response. This replaces the whole project timeline; if the project curr…
- `GET /api/v1/projects/{project_id}/timeline/export/otio` - Export project timeline as OTIO - Exports a saved project's current active timeline as an OpenTimelineIO ZIP bundle. Media references in the OTIO file are portable filenames, not server paths, storage roots, private bucket keys, or signed URLs.
- `POST /api/v1/timelines/export/otio` - Export timeline document as OTIO - Converts a Kaitoi Timeline Document v1 to an OpenTimelineIO ZIP bundle. The ZIP contains `timeline.otio` and any media files the API can resolve from the authenticated account. OTIO media references are portable filenames, never server pat…
- `POST /api/v1/timelines/import/otio` - Import OTIO to timeline document - Imports an `.otio` file or ZIP bundle into a Kaitoi Timeline Document v1. When media files are present in the ZIP, they are persisted to the authenticated account's library and the returned document references those library filenames. Miss…
- `POST /api/v1/timelines/import/otio/parse` - Parse OTIO to timeline document - Parses an `.otio` file or ZIP bundle into a Kaitoi Timeline Document v1 without persisting uploaded media. Returned media references are portable filenames and warnings explain that media was not stored.
- `GET /api/v1/timelines/schema/kaitoi-timeline-document.v1` - Get timeline document schema - Returns the canonical Kaitoi Timeline Document v1 JSON Schema. This route is unauthenticated so public API clients can validate documents before sending them.
- `POST /api/v1/timelines/validate` - Validate timeline document - Validates a Kaitoi Timeline Document v1 against the same schema enforced by the backend.