# AUTO-GENERATED tier-A mirror spec — do not edit. # Source: openapi/runtime/chains.yaml (runtime 0.71.2) # + 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, #304): 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 description: Filter by chain status schema: type: string enum: - active - concluded - expired - budget_exhausted - name: agent_id in: query description: Filter by the agent whose continuation opened the chain schema: type: string example: agent_V1StGXR8Z5jdHi6B - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query required: false description: Number of results to skip schema: type: integer default: 0 responses: "200": description: List of continuation chains content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: $ref: "#/components/schemas/Chain" total: type: integer limit: type: integer offset: type: integer "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error 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 x-naturali-resource: kind: chain from: chain_id parameters: - $ref: "#/components/parameters/chain_id" responses: "200": description: Continuation chain content: application/json: schema: $ref: "#/components/schemas/Chain" "401": description: Unauthorized "403": description: Forbidden "404": description: Chain not found 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=` 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 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 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.