Kaitoi Labs Node Types API

openapi: 3.2.0
info:
  title: Kaitoi REST Node Types 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: Node Types
paths:
  /api/v1/node-types:
    get:
      tags:
      - Node Types
      summary: List node types
      description: Returns node types available to the authenticated user. Use this endpoint to discover compatible node identifiers before building automation against a graph.
      operationId: nodeTypes.list
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of node types to return. Defaults to 50; capped at 200.
          title: Limit
        description: Maximum number of node types to return. Defaults to 50; capped at 200.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque cursor returned from the previous page.
          title: Cursor
        description: Opaque cursor returned from the previous page.
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Smart search over node type, title, category, description, and tags using the shared node catalog ranking.
          title: Search
        description: Smart search over node type, title, category, description, and tags using the shared node catalog ranking.
      - name: fields
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional comma-separated response projection. `type` is always returned. Omit for the existing full summary response.
          title: Fields
        description: Optional comma-separated response projection. `type` is always returned. Omit for the existing full summary response.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: A page of node type summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicListResponse_PublicNodeTypeSummary_'
        '401':
          description: Missing, malformed, expired, or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '403':
          description: The API key lacks the required scope or account capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '429':
          description: The client or API key exceeded the REST API rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '503':
          description: The shared REST API rate limiter is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/node-type-thumbnails/{node_type}:
    get:
      tags:
      - Node Types
      summary: Get node type thumbnail
      description: 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.
      operationId: nodeTypes.getThumbnail
      parameters:
      - name: node_type
        in: path
        required: true
        schema:
          type: string
          title: Node Type
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Signed thumbnail token returned by nodeTypes.list or nodeTypes.get.
          title: Token
        description: Signed thumbnail token returned by nodeTypes.list or nodeTypes.get.
      - name: index
        in: query
        required: false
        schema:
          type: integer
          maximum: 2
          minimum: 1
          description: Thumbnail index. 1 is primary; 2 is secondary when available.
          default: 1
          title: Index
        description: Thumbnail index. 1 is primary; 2 is secondary when available.
      responses:
        '200':
          description: Node type thumbnail image.
          content:
            application/json:
              schema: {}
        '400':
          description: The node type path or thumbnail source is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '403':
          description: The signed thumbnail URL is invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '404':
          description: The node type or thumbnail was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/node-types/{node_type}:
    get:
      tags:
      - Node Types
      summary: Get node type
      description: 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.
      operationId: nodeTypes.get
      parameters:
      - name: node_type
        in: path
        required: true
        schema:
          type: string
          title: Node Type
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Detailed node type metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicNodeTypeDetail'
        '401':
          description: Missing, malformed, expired, or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '403':
          description: The API key lacks the required scope or account capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '429':
          description: The client or API key exceeded the REST API rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '503':
          description: The shared REST API rate limiter is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '400':
          description: The node type path is malformed or unsafe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '404':
          description: The node type was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PublicNodeTypePin:
      properties:
        name:
          type: string
          title: Name
          description: Pin name defined by the node type.
          examples:
          - prompt
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
          description: Pin data type.
          examples:
          - string
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Human-readable pin label.
          examples:
          - Prompt
        default:
          anyOf:
          - {}
          - type: 'null'
          title: Default
          description: Default value for the pin, when available.
        exposed:
          type: boolean
          title: Exposed
          description: Whether this pin is intended for public interaction.
          default: false
        requirement:
          anyOf:
          - type: string
            enum:
            - required
            - optional
            - defaulted
            - unspecified
          - type: 'null'
          title: Requirement
          description: 'Input declaration: required is an explicit ! marker; optional is ?; defaulted is an unmarked input with a non-null default; unspecified is a legacy input with neither. Defaults do not override !. Omission is supported for optional/defaulted inputs; unspecified is not a promise of optionality. Output pins return null. This is distinct from a Station visitor form''s required setting.'
      type: object
      required:
      - name
      title: PublicNodeTypePin
      example:
        default: ''
        exposed: true
        label: Prompt
        name: prompt
        type: string
    PublicListResponse_PublicNodeTypeSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PublicNodeTypeSummary'
          type: array
          title: Data
          description: Items returned for this page.
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Nextcursor
          description: Opaque cursor for the next page. Omitted when there are no more results.
          examples:
          - eyJzb3J0IjoidXBkYXRlZEF0OmRlc2MsaWQ6ZGVzYyJ9
        hasMore:
          type: boolean
          title: Hasmore
          description: True when another page is available.
      type: object
      required:
      - data
      - hasMore
      title: PublicListResponse[PublicNodeTypeSummary]
      example:
        data: []
        hasMore: false
    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
    PublicNodeTypeDetail:
      properties:
        type:
          type: string
          title: Type
          description: Node type identifier.
          examples:
          - builtin/image/load_image
        title:
          type: string
          title: Title
          description: Node display title.
          examples:
          - Load Image
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: Node category.
          examples:
          - Image
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Short description of what the node does.
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
          description: Icon identifier used by the UI.
          examples:
          - image
        thumbnailUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnailurl
          description: Short-lived signed URL for the node catalog thumbnail, when available.
        thumbnailExpiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Thumbnailexpiresat
          description: Expiration timestamp for thumbnailUrl, when present.
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Search and discovery tags.
          examples:
          - - image
            - loader
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Source namespace for the node type.
          examples:
          - builtin
        inputs:
          items:
            $ref: '#/components/schemas/PublicNodeTypePin'
          type: array
          title: Inputs
          description: Input pins exposed by this node type.
        outputs:
          items:
            $ref: '#/components/schemas/PublicNodeTypePin'
          type: array
          title: Outputs
          description: Output pins exposed by this node type.
      type: object
      required:
      - type
      - title
      title: PublicNodeTypeDetail
      example:
        category: Image
        description: Load an image file into the graph.
        icon: image
        inputs:
        - exposed: true
          label: Image
          name: path
          type: file
        outputs:
        - exposed: false
          label: Image
          name: image
          type: image
        source: builtin
        tags:
        - image
        - loader
        title: Load Image
        type: builtin/image/load_image
    PublicNodeTypeSummary:
      properties:
        type:
          type: string
          title: Type
          description: Node type identifier.
          examples:
          - builtin/image/load_image
        title:
          type: string
          title: Title
          description: Node display title.
          examples:
          - Load Image
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: Node category.
          examples:
          - Image
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Short description of what the node does.
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
          description: Icon identifier used by the UI.
          examples:
          - image
        thumbnailUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnailurl
          description: Short-lived signed URL for the node catalog thumbnail, when available.
        thumbnailExpiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Thumbnailexpiresat
          description: Expiration timestamp for thumbnailUrl, when present.
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Search and discovery tags.
          examples:
          - - image
            - loader
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Source namespace for the node type.
          examples:
          - builtin
      type: object
      required:
      - type
      - title
      title: PublicNodeTypeSummary
      example:
        category: Image
        description: Load an image file into the graph.
        icon: image
        source: builtin
        tags:
        - image
        - loader
        title: Load Image
        type: builtin/image/load_image
    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.