# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/chains.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/chains.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Chains API
  version: 1.0.0
  description: >-
    Chains: the continuation chains a project's agents opened — each the population of generations
    descending from one root because every hop continued the one before it, with the count of how
    far it has grown and the status saying whether it is still spending. Read-only: a chain is
    opened by the platform the first time a generation continues another, and the size one may reach
    is set on the agent, not here. A fully runtime-backed module — this spec is generated verbatim
    from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is
    authorized by naturali and enforced upstream by the project's scoped credential.


    This module mirrors the upstream runtime verbatim (tier A): paths are the runtime's own
    re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape
    passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by
    naturali itself (authentication, project resolution, an unreachable runtime) use naturali's.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: "{baseUrl}"
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Chains
    description: Inspect continuation chains and how large they have grown
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/chains:
    get:
      tags:
        - Chains
      summary: List continuation chains
      description: Returns the continuation chains in a project, newest first. Filter by `status` to find
        the chains that may still be spending (`active`) or the ones a budget stopped
        (`budget_exhausted`).
      operationId: listChains
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by chain status. Repeat the parameter to OR values. A value outside the enum,
            empty string included, is a `400`.
          schema:
            type: array
            items:
              type: string
              enum:
                - active
                - concluded
                - expired
                - budget_exhausted
          style: form
          explode: true
        - name: agent_id
          in: query
          description: Filter by the agent whose continuation opened the chain
          schema:
            type: string
            example: agent_V1StGXR8Z5jdHi6B
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of continuation chains
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Chain"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/chains/{chain_id}:
    get:
      tags:
        - Chains
      summary: Get a continuation chain
      description: Returns a single continuation chain. To read the generations in it, list generations
        filtered by `chain_id`.
      operationId: getChain
      parameters:
        - $ref: "#/components/parameters/chain_id"
      responses:
        "200":
          description: Continuation chain
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Chain"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Chain not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    Chain:
      type: object
      properties:
        id:
          type: string
          example: chain_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
        agent_id:
          x-naturali-ref: agents
          type: string
          nullable: true
          description: The agent whose continuation opened the chain. A chain can span agents, so this names
            its origin rather than an owner. Held as a plain id, not a reference the platform
            maintains — deleting the agent leaves the chain record intact.
        status:
          type: string
          enum:
            - active
            - concluded
            - expired
            - budget_exhausted
          description: "`active` — hops are still being spawned. `concluded` — a member finished with nothing
            left pending; not terminal, since a decision months later can spawn another hop and put
            the chain back to `active`. `expired` — a held approval lapsed and the agent does not
            react to expiry, so nothing resumed it. `budget_exhausted` — a hop was refused by the
            chain budget."
        generation_count:
          type: integer
          description: Generations in the chain, the root included — the same population `GET
            /v1/projects/{project_id}/generations?chain_id=<id>` returns. Re-derived on every hop,
            so it is a description of the chain, never the thing the budget is enforced against.
        last_generation_at:
          type: string
          format: date-time
          nullable: true
          description: When the chain last gained a generation
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    chain_id:
      name: chain_id
      in: path
      required: true
      description: Continuation chain ID
      schema:
        type: string
        example: chain_V1StGXR8Z5jdHi6B
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an
        integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`; omit it for the first page. A cursor this list did
        not issue is `400`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: "A connected app's OAuth access token, issued by this API's authorization server
        (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation,
        confined to the projects the user chose when approving the app."
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: "`QUOTA_EXCEEDED` — a `requests` quota on the calling API key or its project is spent
        for the window; `Retry-After` says when it reopens"
      headers:
        Retry-After:
          description: Seconds until the quota window admits a request again
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Unexpected server error — `INTERNAL_ERROR`, with the raw message never forwarded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProjectNotFound:
      description: The project does not exist or the caller is not a member of it (`RESOURCE_NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
