Kaitoi Labs Account API

openapi: 3.2.0
info:
  title: Kaitoi REST Account 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:
- name: Account
paths:
  /api/v1/account/credits:
    get:
      tags:
      - Account
      summary: Get account credits
      description: Returns the authenticated user's current spendable account credit balance and PAYG/subscription breakdown. Requires the `account_credits:read` scope.
      operationId: account.getCredits
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Current account credit balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAccountCredits'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '403':
          description: The API key is missing the required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '503':
          description: Managed billing is not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PublicAccountCredits:
      properties:
        balanceCents:
          type: integer
          title: Balancecents
          description: Total spendable account balance in credits/cents.
          examples:
          - 1250
        balanceMicrocredits:
          type: string
          title: Balancemicrocredits
          description: Exact spendable balance in millionths of one credit.
          examples:
          - '1250110000'
        ledgerUnitVersion:
          type: integer
          title: Ledgerunitversion
          description: Authoritative account-ledger unit version.
        balanceDollars:
          type: number
          title: Balancedollars
          description: Total spendable balance in USD dollars.
          examples:
          - 12.5
        paygBalanceCents:
          type: integer
          title: Paygbalancecents
          description: Purchased pay-as-you-go balance in credits/cents.
          examples:
          - 750
        paygBalanceMicrocredits:
          type: string
          title: Paygbalancemicrocredits
        paygBalanceDollars:
          type: number
          title: Paygbalancedollars
          description: Purchased pay-as-you-go balance in USD dollars.
          examples:
          - 7.5
        subscriptionBalanceCents:
          type: integer
          title: Subscriptionbalancecents
          description: Included subscription balance in credits/cents.
          examples:
          - 500
        subscriptionBalanceMicrocredits:
          type: string
          title: Subscriptionbalancemicrocredits
        subscriptionBalanceDollars:
          type: number
          title: Subscriptionbalancedollars
          description: Included subscription balance in USD dollars.
          examples:
          - 5.0
        subscriptionMonthlyGrantCents:
          type: integer
          title: Subscriptionmonthlygrantcents
          description: Monthly subscription credit grant in credits/cents.
          examples:
          - 1000
        subscriptionMonthlyGrantMicrocredits:
          type: string
          title: Subscriptionmonthlygrantmicrocredits
        subscriptionRolloverCapCents:
          type: integer
          title: Subscriptionrollovercapcents
          description: Maximum subscription rollover balance in credits/cents.
          examples:
          - 2000
        subscriptionRolloverCapMicrocredits:
          type: string
          title: Subscriptionrollovercapmicrocredits
        managedProviderReceivableMicrocredits:
          type: string
          title: Managedproviderreceivablemicrocredits
          description: Outstanding provider cost that must be repaid before new managed work.
        subscriptionPlanTier:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscriptionplantier
          description: Current subscription plan tier, when available.
        subscriptionPeriodEnd:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Subscriptionperiodend
          description: Current subscription period end, when available.
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updatedat
          description: Timestamp when the balance record was last updated.
      type: object
      required:
      - balanceCents
      - balanceMicrocredits
      - ledgerUnitVersion
      - balanceDollars
      - paygBalanceCents
      - paygBalanceMicrocredits
      - paygBalanceDollars
      - subscriptionBalanceCents
      - subscriptionBalanceMicrocredits
      - subscriptionBalanceDollars
      - subscriptionMonthlyGrantCents
      - subscriptionMonthlyGrantMicrocredits
      - subscriptionRolloverCapCents
      - subscriptionRolloverCapMicrocredits
      - managedProviderReceivableMicrocredits
      title: PublicAccountCredits
      example:
        balanceCents: 1250
        balanceDollars: 12.5
        balanceMicrocredits: '1250110000'
        ledgerUnitVersion: 2
        managedProviderReceivableMicrocredits: '0'
        paygBalanceCents: 750
        paygBalanceDollars: 7.5
        paygBalanceMicrocredits: '750110000'
        subscriptionBalanceCents: 500
        subscriptionBalanceDollars: 5.0
        subscriptionBalanceMicrocredits: '500000000'
        subscriptionMonthlyGrantCents: 1000
        subscriptionMonthlyGrantMicrocredits: '1000000000'
        subscriptionPeriodEnd: '2026-06-30T00:00:00Z'
        subscriptionPlanTier: pro
        subscriptionRolloverCapCents: 2000
        subscriptionRolloverCapMicrocredits: '2000000000'
        updatedAt: '2026-06-09T12:00:00Z'
    PublicApiErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/PublicApiErrorBody'
          description: REST API error payload.
      type: object
      required:
      - error
      title: PublicApiErrorResponse
      example:
        error:
          code: PROJECT_NOT_FOUND
          details:
            projectId: proj_123
          message: Project not found.
    PublicApiErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code.
          examples:
          - PROJECT_NOT_FOUND
        message:
          type: string
          title: Message
          description: Human-readable error summary.
          examples:
          - Project not found.
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Additional structured error details.
          examples:
          - projectId: proj_123
        requestId:
          anyOf:
          - type: string
          - type: 'null'
          title: Requestid
          description: Request identifier echoed from X-Request-Id when provided.
          examples:
          - req_123
      type: object
      required:
      - code
      - message
      title: PublicApiErrorBody
      example:
        code: PROJECT_NOT_FOUND
        details:
          projectId: proj_123
        message: Project not found.
        requestId: req_123
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Programmatic Kaitoi API key.