Kaitoi Labs Timelines API

openapi: 3.2.0
info:
  title: Kaitoi REST Timelines API
  description: '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 `. 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 permissions. For production web apps, the safest pattern is usually: browser frontend calls

    your backend, and your backend calls Kaitoi with a Backend service key. Use

    Browser app keys only when you intentionally want direct browser-to-Kaitoi

    calls and have chosen scopes and quotas accordingly. **Base URL**


    All REST API endpoints are served under `/api/v1`. The global FastAPI

    documentation endpoints remain disabled in production; this OpenAPI document is

    filtered to REST API routes only. **API Artifacts**


    The OpenAPI schema is available at `/api/v1/openapi.json`. A generated Postman

    collection is available at `/api/v1/postman.json` and stays in sync with this

    schema as the REST API grows. LLM-friendly documentation is available at `/api/v1/llms.txt`, with a fuller

    Markdown reference at `/api/v1/llms-full.txt`. **Rate Limits**


    Requests are rate limited per client IP before authentication and per API key

    after authentication. `429 RATE_LIMITED` responses include a `Retry-After`

    header and a JSON error body. Production/staging deployments enforce these

    limits through the shared Redis-backed limiter so quotas apply across backend

    instances. The default production behavior is fail-closed: if the shared

    limiter is unavailable, requests return `503 RATE_LIMIT_UNAVAILABLE` with a

    short `Retry-After` hint so clients back off instead of bypassing quotas. Operators can explicitly configure a per-instance local degradation mode for

    environments that prefer temporary availability over globally strict quotas. Local development uses an in-process fallback unless Redis rate limiting is

    explicitly enabled. **Errors**


    Errors use a consistent shape: `{ "error": { "code", "message", "details" } }`. When clients send `X-Request-Id`, the same identifier is echoed as

    `error.requestId` to simplify support and audit correlation. **Pagination**


    List endpoints use opaque keyset cursors. Treat `nextCursor` as an opaque token;

    do not parse or construct it client-side. **Project Documents**


    Use `/projects/{projectId}/document` as the canonical editable project surface. `GET /projects/{projectId}/graph` is a read-oriented view and is not intended

    to be round-tripped back into document writes. Document writes require

    `expectedVersion` for optimistic concurrency and support idempotent retries. Project read versions are conservative save bases captured before content reads;

    they do not certify exact bytes during concurrent or unresolved writes. A

    protected mutation can return `409 PROJECT_MUTATION_IN_PROGRESS` or

    `409 PROJECT_MUTATION_UNRESOLVED`. The latter must not be treated as a stale-copy

    reload or a timed retry: preserve local work and inspect the original operation,

    or save a new copy. `503 PROJECT_SAVE_UNAVAILABLE` and

    `503 PROJECT_STATE_UNAVAILABLE` also require preserving local work.'
  version: 1.0.0
security:
- BearerAuth: []
tags:


# --- truncated at 32 KB (41 KB total) ---
# Full source: https://artifacts.apis.io/kaitoi-io/openapi/kaitoi-io-timelines-api-openapi.yml