# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/generations.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/generations.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Generations API
  version: 1.0.0
  description: >-
    Generations: one model loop each — the record an agent, session or conversation generation is
    polled and audited through, with its transcript and its content-purge control. 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: Generations
    description: Inspect generation records
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/generations:
    get:
      tags:
        - Generations
      summary: List generations
      description: >
        Returns generations the caller can access, optionally filtered by agent, trace,
        orchestration run, node, and status. The generations of one trace are the `trace_id` filter.


        Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to
        the generations its agent nodes produced: a node execution record carries no generation id,
        so the pointer lives here, alongside the run's other attribution columns.
      operationId: listGenerations
      parameters:
        - name: agent_id
          in: query
          required: false
          description: Filter by agent public ID
          schema:
            type: string
        - name: trace_id
          in: query
          required: false
          description: Filter by trace public ID
          schema:
            type: string
        - name: session_id
          in: query
          required: false
          description: >
            Return only the generations dispatched through one session — the turns behind that
            conversation's spend. A session that does not exist in scope yields an empty page.
          schema:
            type: string
        - name: actor_id
          in: query
          required: false
          description: >
            Return only the generations one end user started, across every session they appear in.
            An actor that does not exist in scope yields an empty page.
          schema:
            type: string
        - name: initiator_generation_id
          in: query
          required: false
          description: >
            Filter by the public ID of the parent generation. Returns every generation started by
            that generation: sub-agent invocations, approval continuations, client-tool re-handoffs
            and memory-rule handler turns. Top-level generations are not returned.
          schema:
            type: string
        - name: chain_id
          in: query
          required: false
          description: >
            Filter by the continuation chain the generation belongs to. This is how a chain is
            expanded into its members — the chain record carries only their count.
          schema:
            type: string
        - name: orchestration_run_id
          in: query
          required: false
          description: >
            Filter by the orchestration run that dispatched the generation. This is how a run is
            traced back to what its agent nodes did — a node execution record stores no generation
            id.
          schema:
            type: string
        - name: node_id
          in: query
          required: false
          description: >
            Filter by the orchestration node that dispatched the generation. Combine with
            `orchestration_run_id` to narrow to one node of one run; a retried node returns one
            generation per `node_attempt`.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by lifecycle 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:
                - running
                - requires_action
                - completed
                - failed
          style: form
          explode: true
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Paginated list of generations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Generation"
        "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":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/generations/{generation_id}:
    get:
      tags:
        - Generations
      summary: Get a generation
      description: >
        Returns a single generation record by ID, including its status and the structured `error`
        payload when the generation failed (e.g. because the upstream AI provider returned an
        error).
      operationId: getGeneration
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
      responses:
        "200":
          description: Generation details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generation"
        "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: Generation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - Generations
      summary: Update generation metadata
      description: >
        Attaches caller-supplied key/value metadata to a generation record for per-run audit
        attribution (e.g. the ticket or case an AI action belongs to). The provided keys are
        shallow-merged over the existing `metadata`, so repeated patches accumulate. The bag is
        caller-owned and no key is reserved: server-owned state (usage attribution, the served agent
        version, the route's record, the extraction summary, what knowledge retrieval served) lives
        in its own top-level fields and cannot be written from here.
      operationId: updateGeneration
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGenerationRequest"
            examples:
              audit:
                summary: Attach caller audit metadata
                value:
                  metadata:
                    team: payments
                    ticket_id: OPS-4821
      responses:
        "200":
          description: Updated generation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generation"
        "400":
          description: Bad Request (e.g. metadata is not a JSON object)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Generation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/generations/{generation_id}/content:
    delete:
      tags:
        - Generations
      summary: Purge generation content
      description: >
        Clears the generation's content — `metadata`, `error`, `extraction`, and the internal
        recovery state of a paused run — and stamps `content_redacted_at`.


        The usage and audit skeleton is preserved: ids, timestamps, status, stop reason, and the
        attribution fields (`action_id`, `trigger_id`, `orchestration_run_id`, `node_id`,
        `node_attempt`, `agent_version`, `routing`) the billing ledger reads. A purged generation
        reads back as that skeleton, not a 404.


        This does **not** delete the parent trace's steps object, which holds this generation's
        content alongside its siblings'. To erase the run's content completely, purge the trace
        (`DELETE /v1/projects/{project_id}/traces/{trace_id}/content`), which cascades here.


        Idempotent — purging an already-purged generation succeeds and leaves the original
        `content_redacted_at` in place.
      operationId: purgeGenerationContent
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
      responses:
        "200":
          description: The purged generation skeleton
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Generation"
        "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: Generation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/generations/{generation_id}/memory-assertions:
    get:
      tags:
        - Generations
      summary: List the memory writes a generation made
      description: >
        Every memory write this turn made, oldest first: each memory rule's firings and the agent's
        own `write_memory` calls alike. The rows behind the generation's per-rule `extraction`
        counts. Reading them is reading the generation (`generations:GetGeneration`).
      operationId: listGenerationMemoryAssertions
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: The generation's memory writes
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/MemoryAssertion"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Generation 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"
  /v1/projects/{project_id}/generations/{generation_id}/transcript:
    get:
      tags:
        - Generations
      summary: Get a generation's transcript
      description: >
        Returns one generation's turn read back as an ordered sequence of steps: what it was asked,
        each model step with its tool calls and results, and how it ended.


        The transcript is assembled at read time from the generation record and the trace's steps
        object; nothing is stored, so it cannot outlive the content it projects. Requires
        `traces:GetTrace` in addition to `generations:GetGeneration`, because the response merges
        content from both resources.


        A generation whose content is unavailable — never written under zero-retention, or cleared
        by a purge — returns `200` with the skeleton rather than an error: `input` and `output` are
        null, `steps` is empty, and the `content_redacted_*` fields say which happened.
        `content_redacted_by_principal_id` is `zero_retention` when the content was never stored,
        and the purging principal's ID when it was erased later. A generation that is still running
        returns the steps it has ended so far and its `in_flight_tool_calls`; `status` says it runs.
        To follow it as it runs, read `GET
        /v1/projects/{project_id}/generations/{generation_id}/events`.
      operationId: getGenerationTranscript
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
      responses:
        "200":
          description: The generation's transcript
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerationTranscript"
        "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: Generation 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"
  /v1/projects/{project_id}/generations/{generation_id}/events:
    get:
      tags:
        - Generations
      summary: List a generation's events
      description: >
        The generation's transcript, incrementally: its progress rows in `seq` order, after
        `after_seq`. Each `generations.step_ended` row carries the step it ended as a
        `TranscriptStep`; the other rows say when a step or a tool call started and ended, and which
        generation a tool call started.


        Step content and tool names are the trace's content: reading them needs `traces:GetTrace` on
        the generation's trace beside `generations:GetGeneration`, and is refused with `403` without
        it. `progress_only=true` asks for the rows alone (`step` is null), which
        `generations:GetGeneration` alone allows. Content is re-read on every page: once a purge
        erases it, or under zero-retention, `step` is null.


        `stream=true` answers `text/event-stream` instead and follows the generation until it
        settles (`completed`, `failed` or `requires_action`), or stops running without a settle row.
        Each row is one `event: progress` frame whose `id` is its `seq`; the stream ends with `data:
        [DONE]`. A `: heartbeat` comment is sent every 15 seconds. After 5 minutes the stream ends
        with `event: end` and `data: {"reason": "max_lifetime", "generation_id": "...", "after_seq":
        N}`: reconnect with that `after_seq`, or let an `EventSource` reconnect with its
        `Last-Event-ID` header, which this route reads as `after_seq`. Every reconnect is authorized
        afresh.
      operationId: listGenerationEvents
      parameters:
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
          description: Public ID of the generation
        - name: after_seq
          in: query
          required: false
          description: >
            Return the rows after this `seq`. Defaults to the `Last-Event-ID` header when sent, else
            `0` (from the first row).
          schema:
            type: integer
            minimum: 0
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: progress_only
          in: query
          required: false
          description: |
            When `true`, the rows without step content, which needs no `traces:GetTrace`.
          schema:
            type: boolean
            default: false
        - name: stream
          in: query
          required: false
          x-naturali-tool-unsupported: true
          description: |
            When `true`, answer `text/event-stream` and follow the generation until it settles.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: A page of the generation's events, or their stream
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerationEventsPage"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/GenerationEventStream"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Forbidden: no `generations:GetGeneration` on the generation, or no `traces:GetTrace`
            on its trace without `progress_only=true`"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Generation 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:
    Generation:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the generation
          example: gen_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          description: Public ID of the project
        agent_id:
          x-naturali-ref: agents
          type: string
          description: Public ID of the agent that ran this generation
        trace_id:
          x-naturali-ref: traces
          type: string
          description: Public ID of the trace this generation belongs to
        initiator_generation_id:
          x-naturali-ref: generations
          type: string
          nullable: true
          description: >
            Public ID of the generation that started this one: a sub-agent invocation, an approval
            continuation, a client-tool re-handoff or a memory-rule handler turn. Null for top-level
            generations.
        chain_id:
          x-naturali-ref: chains
          type: string
          nullable: true
          description: >
            Public ID of the continuation chain this generation belongs to. Set on every member of a
            chain — the continuations and the root they descend from — and null on a generation that
            is not part of one.
        conversation_id:
          x-naturali-ref: conversations
          type: string
          nullable: true
          description: >
            Public ID of the conversation this turn served, or null for a generation started outside
            one — a direct call, a trigger, an orchestration node. This is the edge a memory
            assertion walks up to reach the conversation a fact was learned in.
        session_id:
          x-naturali-ref: sessions
          type: string
          nullable: true
          description: >
            Public ID of the session this generation was dispatched through, or null for a
            generation started outside one. This is the link a per-session cost reading follows; the
            session's own `usage` field reports the roll-up directly.
        actor_id:
          x-naturali-ref: actors
          type: string
          nullable: true
          description: >
            Public ID of the end-user actor the generation was attributed to, or null when none was.
            Copied onto the generation's usage event.
        started_by_principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: Who started the generation
        started_by_principal_id:
          type: string
          nullable: true
          description: "Public id of that principal: the user (`user_…`), or for API key auth the key itself
            (`key_…`), so the record names which key acted."
          example: user_V1StGXR8Z5jdHi6B
        acted_as:
          type: object
          nullable: true
          description: "The principal the latest segment's tool calls ran as: the starter, or the agent when
            it runs under its own grant (`run_as: agent`). A caller who resumes the generation by
            submitting its tool outputs only narrows what it may do. A tool call an approval held
            runs, once approved, as this principal. Null when the segment ran with no principal."
          required:
            - principal_type
            - principal_id
          properties:
            principal_type:
              $ref: "#/components/schemas/PrincipalType"
            principal_id:
              type: string
              example: user_V1StGXR8Z5jdHi6B
        acts_for:
          type: object
          nullable: true
          description: "The opaque principal the starter acted for: the `principal` of the IAM token that
            started the generation, or the one an `On-Behalf-Of` assertion carried.
            `started_by_principal_*` names the key that minted the token. A resume keeps the
            starter's. Null when the starter named none."
          required:
            - type
            - id
          properties:
            type:
              type: string
              example: channel
            id:
              type: string
              example: discord-dm-42
        status:
          type: string
          description: Lifecycle status of the generation
          enum:
            - running
            - requires_action
            - completed
            - failed
          example: failed
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: When the generation reached a terminal state
        last_activity_at:
          type: string
          format: date-time
          nullable: true
        stop_reason:
          type: string
          nullable: true
          description: >
            Why the generation stopped. Either the model provider's own finish reason relayed
            unchanged ('stop', 'tool-calls', 'length', …) or one the platform names itself:
            'max_steps' when the turn spent its whole step budget on tool calls, 'depth_guard' when
            a nested call exceeded the call depth, 'chain_limit' when a continuation chain reached
            its generation budget, or 'error' when the turn failed.
          example: error
        error:
          allOf:
            - $ref: "#/components/schemas/StoredError"
          nullable: true
          description: "Why the generation failed: `AI_PROVIDER_ERROR` for an upstream provider failure,
            `GENERATION_FAILED` for any other failure of the turn."
        action_id:
          type: string
          nullable: true
          description: >
            Logical action label supplied on the generate request. Recorded on the generation's
            usage event for per-action spend rollups.
        trigger_id:
          x-naturali-ref: triggers
          type: string
          nullable: true
          description: Trigger that initiated the generation, when applicable
        orchestration_run_id:
          x-naturali-ref: orchestration-runs
          type: string
          nullable: true
          description: |
            Orchestration run that dispatched the generation. Null for a standalone generation.
        node_id:
          type: string
          nullable: true
          description: >
            Node within `orchestration_run_id` that dispatched the generation. Together with the run
            it forms the usage event's replay identity.
        node_attempt:
          type: integer
          nullable: true
          description: >
            The node's 1-based retry attempt, completing the run + node + attempt replay identity. A
            retried node produces one generation per attempt; this is what tells them apart. Null
            for a generation no orchestration node dispatched.
        agent_version:
          type: integer
          nullable: true
          description: >
            Agent config version that served this generation, resolved by the served-version
            resolver (see [agent versions](/docs/modules/agents#versioning-and-staged-rollout)).
        source:
          type: string
          nullable: true
          description: >
            What produced the generation besides production traffic: `eval` for an eval run,
            `decider` for a decider question. `null` for production traffic.
          example: eval
        extraction:
          type: object
          nullable: true
          description: >
            What each [memory rule](/docs/modules/memory-rules) bound to `generations.completed`
            wrote for this turn, keyed by the rule's id — a store may have several rules, and one
            flat pair of counts could not say which produced them. Absent when no rule fired. Rules
            bound to `conversation_messages.generated` are recorded only as memory assertions. The
            rows behind every count are listed by `GET
            /v1/projects/{project_id}/generations/{generation_id}/memory-assertions`, so the summary
            and what it summarizes can be reconciled.
          additionalProperties:
            type: object
            properties:
              candidates:
                type: integer
                description: Number of candidates the rule's handler proposed
              created:
                type: integer
                description: Number of new memories created
              superseded:
                type: integer
                description: >
                  Number of candidates that restated a known fact that had changed, retiring the
                  memory holding it
              skipped:
                type: integer
                description: Number of candidates skipped (e.g. duplicates)
        tool_surface:
          type: object
          nullable: true
          description: >-
            What this turn's tool definitions cost to send — the one part of a prompt no provider
            reports and no caller can derive, since the tool block is a constant inside the reported
            totals and identical on every step.


            Null when the surface was never measured: a generation from before the field, or a path
            that resolves none. That is **not** what `tools: 0` means, which is a measured agent
            with nothing bound.


            Not a meter. `estimated_tokens` is an estimate and is never priced — `usage` and the
            usage events are the billing record.
          properties:
            tools:
              type: integer
              description: Tools resolved for the turn, before any per-step narrowing by `step_rules`.
              example: 61
            bytes:
              type: integer
              description: Serialized length of those definitions — name, description and input schema — in
                canonical JSON, not the provider's wire format. Exact, and comparable across
                providers, which is what makes two agents' surfaces worth comparing.
              example: 152161
            estimated_tokens:
              type: integer
              description: "`bytes` over a measured bytes-per-token ratio. An estimate, and named one."
              example: 45148
        retrieval:
          type: array
          nullable: true
          description: >-
            What `knowledge_config` retrieval injected into this turn, in the order it was injected:
            which document, at which version, and which chunk, or which memory. Written by the
            server at turn start and never writable; pointers only, never the text.


            Null when no retrieval ran — the agent has no `knowledge_config`, or the turn had
            neither a query nor a filter to search with. An empty array is a retrieval that ran and
            matched nothing.


            Not content: a content purge leaves it standing, and zero retention still writes it.
            `document_version` names an archived version, so the text the turn read stays readable
            after the document changes.
          items:
            oneOf:
              - $ref: "#/components/schemas/GenerationRetrievedDocument"
              - $ref: "#/components/schemas/GenerationRetrievedMemory"
            discriminator:
              propertyName: source_type
              mapping:
                document: "#/components/schemas/GenerationRetrievedDocument"
                memory: "#/components/schemas/GenerationRetrievedMemory"
        idempotency_key:
          type: string
          nullable: true
          description: The deduplication key the generation was started under, unique within the project and
            claimed for as long as the generation record exists. Null for a generation started
            without one.
          example: discord-1287654321098765432
        usage:
          allOf:
            - $ref: "#/components/schemas/UsageTotals"
          nullable: true
          description: >-
            What the turn cost: token counts and `cost_usd` for every event metered against this
            generation. Present on the single-generation read; omitted from the listing, where it
            would be a query per row.


            Null when nothing has been metered yet — a turn still in flight, or one whose metering
            failed. A turn is metered once at the end, so this is one event's figures in the
            ordinary case.
        routing:
          type: object
          nullable: true
          description: >
            What the model route did for this generation. Present only when the agent resolves its
            model through a `model_route_id`.
          properties:
            route_id:
              x-naturali-ref: model-routes
              type: string
              description: The route that resolved the model
            target_index:
              type: integer
              nullable: true
              description: >
                Position in the route's `targets` of the target that served the last LLM call; null
                when every attempt failed.
            fallbacks:
              type: integer
              description: >
                How many times the route moved past a target during this generation (cumulative
                across a multi-step run).
            attempts:
              type: array
              description: >
                Every attempt, in order, across every LLM call of the run. An attempt with no
                `error_class` succeeded.
              items:
                type: object
                properties:
                  target_index:
                    type: integer
                  ai_provider_id:
                    x-naturali-ref: ai-providers
                    type: string
                  model:
                    type: string
                  error_class:
                    type: string
                    enum:
                      - provider_error
                      - timeout
                      - rate_limited
                    description: >
                      Why the attempt failed. Absent on the serving attempt, and absent on a
                      deterministic failure (which fails the generation instead of failing over).
        metadata:
          description: >
            Caller-owned key/value annotations, attached at create time (via the `metadata` field on
            the create-agent-generation request) or afterwards (via the update-generation request),
            and returned verbatim. The server writes nothing here: every piece of state it owns —
            usage attribution, the served agent version, the route's record, the extraction summary,
            internal recovery state — is a field of its own, so no key written here can reach
            platform state. Keys are never transformed, and no key is reserved.
          example:
            team: payments
            ticket_id: OPS-4821
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
        content_redacted_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When the generation's content was purged. Non-null means `metadata`, `error`,
            `extraction` and the internal recovery state have been cleared, while the usage/audit
            skeleton — ids, timestamps, status, stop reason and the attribution fields — is
            preserved.
        content_redacted_by_principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: "Who purged the content: `user` or `api_key` for a purge request, `system` for the
            retention sweep and for content never stored under zero retention."
        content_redacted_by_principal_id:
          type: string
          nullable: true
          description: Public id of that principal — the API key's own id for key auth, so the record names
            which key acted. `retention_sweep` or `zero_retention` for `system`.
          example: user_V1StGXR8Z5jdHi6B
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    GenerationRetrievedDocument:
      type: object
      required:
        - source_type
        - document_id
        - document_version
        - chunk_id
        - page
        - similarity_score
      properties:
        source_type:
          type: string
          enum:
            - document
          example: document
        document_id:
          x-naturali-ref: documents
          type: string
          description: Public ID of the document the chunk belongs to
          example: doc_V1StGXR8Z5jdHi6B
        document_version:
          type: integer
          nullable: true
          description: The document version the chunk was read from. Read it back with the document's versions
            to see the exact text the turn was given.
          example: 3
        chunk_id:
          type: string
          description: Public ID of the injected chunk. Stops resolving once the document is re-chunked;
            `document_version` is the durable pointer.
          example: dchunk_V1StGXR8Z5jdHi6B
        page:
          type: integer
          nullable: true
          description: Page within the source PDF (1-indexed). Null for plain text.
          example: 2
        similarity_score:
          type: number
          nullable: true
          description: Raw cosine similarity (0–1) between the turn's query and the result. Null when the turn
            had no query, or the search answered from the lexical channel alone. The rank is the
            array order.
          example: 0.82
    GenerationRetrievedMemory:
      type: object
      required:
        - source_type
        - memory_store_id
        - memory_id
        - similarity_score
      properties:
        source_type:
          type: string
          enum:
            - memory
          example: memory
        memory_store_id:
          x-naturali-ref: memory-stores
          type: string
          description: Public ID of the memory store the memory belongs to
          example: mstore_V1StGXR8Z5jdHi6B
        memory_id:
          type: string
          description: Public ID of the injected memory
          example: mem_V1StGXR8Z5jdHi6B
        similarity_score:
          type: number
          nullable: true
          description: Raw cosine similarity (0–1) between the turn's query and the result. Null when the turn
            had no query, or the search answered from the lexical channel alone. The rank is the
            array order.
          example: 0.82
    UpdateGenerationRequest:
      type: object
      required:
        - metadata
      additionalProperties: false
      properties:
        metadata:
          description: >
            Caller-supplied key/value metadata to shallow-merge into the generation record's
            caller-owned `metadata` bag. No key is reserved: server-owned state lives in its own
            top-level fields and cannot be written from here.
          example:
            team: payments
            ticket_id: OPS-4821
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
    TranscriptToolCall:
      type: object
      description: One tool call the model made during a step.
      properties:
        id:
          type: string
          nullable: true
          description: >
            The call's ID, as the model provider issued it (e.g. `call_…`), used to correlate it
            with an entry in `tool_results`. Null when the stored step did not record one.
        tool_name:
          type: string
          nullable: true
          example: weather
        args:
          description: >
            The arguments the model supplied, as a value. This payload is tool-owned: its keys are
            passed through exactly as they were recorded and are never inspected or rewritten by the
            runtime.
          example:
            cityName: Paris
    TranscriptToolResult:
      type: object
      description: >
        One tool's answer to a call in the same step. A call that failed is reported here too, with
        `result` null and `error` set — so a reader sees successes and failures in one ordered list
        keyed by the call they answer.
      properties:
        tool_call_id:
          type: string
          nullable: true
          description: The `id` of the `tool_calls` entry this answers.
        tool_name:
          type: string
          nullable: true
          example: weather
        result:
          description: >
            What the tool returned, as a value. Tool-owned: keys are passed through verbatim. Null
            when the call errored.
          example:
            tempC: 18
        error:
          allOf:
            - $ref: "#/components/schemas/StoredError"
          nullable: true
          description: The tool's failure, when the step recorded one. A failure the tool raised with a code
            keeps it; any other is `TOOL_CALL_FAILED`, with the fields the thrown error carried
            (`name`, `status`, …) in `meta`.
          example: null
    GenerationEvent:
      type: object
      description: >
        One progress row of a generation. Ids, positions, statuses and times only, except `step`,
        which carries an ended step's content.
      required:
        - seq
        - type
        - created_at
      properties:
        seq:
          type: integer
          description: >
            Position of the row in the generation's sequence, from 1 and gapless; the cursor
            `after_seq` reads after.
          example: 3
        type:
          type: string
          enum:
            - generations.started
            - generations.step_started
            - generations.step_ended
            - generations.tool_call_started
            - generations.tool_call_ended
            - generations.sub_generation_started
            - generations.completed
            - generations.failed
            - generations.requires_action
          example: generations.tool_call_ended
        step_index:
          type: integer
          nullable: true
          description: Index of the step the row belongs to.
          example: 0
        tool_call_id:
          type: string
          nullable: true
          description: The model's id for the tool call the row belongs to.
          example: V1StGXR8Z5jdHi6B
        status:
          type: string
          nullable: true
          description: >
            How a tool call ended (`executed`, `failed`, or the status of a call something else
            answered), or the settled status on a settle row.
          example: executed
        duration_ms:
          type: integer
          nullable: true
          description: How long the tool call ran, on `generations.tool_call_ended`.
          example: 412
        child_generation_id:
          x-naturali-ref: generations
          type: string
          nullable: true
          description: |
            The generation a tool call started, on `generations.sub_generation_started`.
          example: gen_V1StGXR8Z5jdHi6B
        created_at:
          type: string
          format: date-time
        step:
          allOf:
            - $ref: "#/components/schemas/TranscriptStep"
          nullable: true
          description: >
            The step a `generations.step_ended` row ended, with its tool calls and results. Null on
            every other row, with `progress_only=true`, and when the content is unavailable.
    GenerationEventsPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - generation_id
            - status
          properties:
            generation_id:
              x-naturali-ref: generations
              type: string
              example: gen_V1StGXR8Z5jdHi6B
            status:
              type: string
              description: >
                The generation's status when the page was read. While it is `running`, read on from
                the last row's `seq` as `after_seq`.
              enum:
                - running
                - requires_action
                - completed
                - failed
              example: running
            data:
              type: array
              items:
                $ref: "#/components/schemas/GenerationEvent"
    GenerationEventStream:
      type: string
      description: >
        SSE frames. Each progress row is an `event: progress` frame with `id: <seq>` and the
        `GenerationEvent` as `data`. The stream ends with `data: [DONE]` once the generation settles
        or stops running. A `: heartbeat` comment is sent every 15 seconds. After 5 minutes it ends
        with `event: end` and `data: {"reason": "max_lifetime", "generation_id": "...", "after_seq":
        N}`; reconnect from that `after_seq`, or with the last frame's `id` as `Last-Event-ID`. A
        failure after the stream opened is a terminal `data: {"error": {...}}` frame without
        `[DONE]`.
    TranscriptStep:
      type: object
      description: >
        One model step. Projected from the stored step at read time — the stored shape is provider-
        and SDK-specific and is never put on the wire.
      properties:
        index:
          type: integer
          description: >
            Zero-based position of this step in the turn. Positional rather than the model's own
            step number, which restarts at zero when a paused turn resumes.
          example: 0
        text:
          type: string
          description: |
            The text this step produced. Empty for a step that only called tools.
          example: ""
        finish_reason:
          type: string
          nullable: true
          description: Why this step stopped.
          example: tool-calls
        tool_calls:
          type: array
          items:
            $ref: "#/components/schemas/TranscriptToolCall"
        tool_results:
          type: array
          items:
            $ref: "#/components/schemas/TranscriptToolResult"
        usage:
          allOf:
            - $ref: "#/components/schemas/UsageTotals"
          nullable: true
          description: What this step reported, in the shape every usage surface uses. Null when the step
            recorded no usage at all; within a step a dimension the provider did not report reads 0.
            `cost_usd` is always null here — the ledger prices one event per generation, so a
            per-step price would disagree with it after any price change.
    InFlightToolCall:
      type: object
      description: A tool call that started and has not finished.
      properties:
        tool_call_id:
          type: string
          nullable: true
          description: The model's id for the call, as its step records it.
          example: V1StGXR8Z5jdHi6B
        step_index:
          type: integer
          nullable: true
          description: Index of the step the call belongs to.
          example: 1
        started_at:
          type: string
          format: date-time
    GenerationTranscript:
      type: object
      description: >
        One generation's turn, read back step by step. Assembled at read time from the generation
        record and the trace's steps object — never stored, so it dies with the content it projects.
      properties:
        generation_id:
          x-naturali-ref: generations
          type: string
          example: gen_V1StGXR8Z5jdHi6B
        trace_id:
          x-naturali-ref: traces
          type: string
          nullable: true
          example: trace_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
        agent_id:
          x-naturali-ref: agents
          type: string
        agent_version:
          type: integer
          nullable: true
          description: Agent config version that served the turn.
        status:
          type: string
          description: >
            Lifecycle status of the generation. Disambiguates an empty `steps` caused by a run still
            in flight from one caused by erased content.
          enum:
            - running
            - requires_action
            - completed
            - failed
          example: completed
        stop_reason:
          type: string
          nullable: true
          description: >
            Why the generation stopped — the provider's finish reason, or one of the platform's own
            ('max_steps', 'depth_guard', 'chain_limit', 'error').
          example: stop
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        step_count:
          type: integer
          description: >
            Number of steps this turn recorded. A counter rather than content, so it survives a
            purge and still reports the size of a turn whose steps are gone. Scoped to the
            generation, not the trace: a trace that groups several generations counts them all in
            its own `step_count`, while each transcript reports only its own.
          example: 2
        input:
          type: array
          nullable: true
          description: >
            The messages the turn was asked, as recorded. Message content is caller-owned and passed
            through verbatim. Null when the content was never stored or has been purged.
          items:
            type: object
        steps:
          type: array
          description: >
            The turn's steps in order: for a running turn, the steps ended so far. Empty for a turn
            with no ended step, and for one whose content is unavailable — `status` and
            `content_redacted_at` say which.
          items:
            $ref: "#/components/schemas/TranscriptStep"
        in_flight_tool_calls:
          type: array
          description: >
            The tool calls a running turn started and has not finished, in start order. Empty unless
            `status` is `running`. Ids and times only, so present whatever the content mode; the
            call's name and arguments arrive with its step.
          items:
            $ref: "#/components/schemas/InFlightToolCall"
        output:
          type: object
          nullable: true
          description: |
            The turn's final answer. Null when there are no steps to derive it from.
          properties:
            content:
              type: string
              nullable: true
              description: |
                The last step that produced text. Null for a turn that only called tools.
              example: It's 18°C in Paris right now.
            finish_reason:
              type: string
              nullable: true
              description: The finish reason of the actual last step.
              example: stop
        error:
          allOf:
            - $ref: "#/components/schemas/StoredError"
          nullable: true
          description: Why the generation failed.
        content_redacted_at:
          type: string
          format: date-time
          nullable: true
          description: |
            When the generation's content was erased; null while it is intact.
        content_redacted_by_principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: Who erased the content.
        content_redacted_by_principal_id:
          type: string
          nullable: true
          description: >
            Public id of that principal. `zero_retention` when the content was never stored,
            distinguishing it from content erased later.
    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`.
    MemoryAssertion:
      type: object
      description: "One write attempt against a memory store: some principal, through some mechanism,
        claimed a fact. Append-only, and recorded whatever the outcome — including the skips, which
        left no record anywhere before."
      properties:
        id:
          type: string
          example: massert_V1StGXR8Z5jdHi6B
        memory_store_id:
          x-naturali-ref: memory-stores
          type: string
          example: mstore_V1StGXR8Z5jdHi6B
        memory_id:
          type: string
          nullable: true
          description: "The memory this assertion resolved into: the new memory for `created` and
            `superseded`, the existing memory that matched for `skipped`, the memory withdrawn for
            `retracted`. Null only once that memory has been deleted."
          example: mem_V1StGXR8Z5jdHi6B
        superseded_memory_id:
          type: string
          nullable: true
          description: The memory this assertion retired, on a `superseded` outcome; null otherwise, a
            retraction included — it retires its own memory, which `memory_id` already names. Read
            back from `memories.superseded_by_memory_id` rather than stored here, because validity
            lives on the memory — where every read filters it — and exactly one memory is superseded
            per assertion.
          example: mem_V1StGXR8Z5jdHi6B
        content:
          type: string
          description: "The text as asserted, which is not necessarily the memory's text: a `skipped`
            assertion records what was claimed, while the memory keeps what it already held."
          example: The customer prefers email communication over phone calls
        mechanism:
          type: string
          enum:
            - tool
            - rule
            - api
            - formation
          description: Which door the write came through. `tool` is the agent's `write_memory` call mid-turn;
            `rule` is a post-turn pass over the finished turn; `api` is `POST
            /v1/projects/{project_id}/memories`; `formation` is a `memory` resource in an applied
            template. It answers *how*, never *who* — the principal fields answer that. Open set —
            new mechanisms may be added in minor releases; clients must tolerate unknown values.
          example: tool
        rule_id:
          x-naturali-ref: memory-rules
          type: string
          nullable: true
          description: The memory rule whose firing wrote this, set only when `mechanism` is `rule` — the
            built-in extractor included, since that is a rule with no handler. Null once the rule
            has been deleted, and on assertions written before memory rules shipped.
          example: mrule_V1StGXR8Z5jdHi6B
        generation_id:
          x-naturali-ref: generations
          type: string
          nullable: true
          description: The turn that asserted the fact — the origin of anything an agent wrote, and the edge a
            conversation is reachable from. Null on the `api` and `formation` doors, which have no
            generation behind them.
          example: gen_V1StGXR8Z5jdHi6B
        principal_type:
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: "Who claimed the fact: `user` or `api_key` on the `api` and `formation` doors, `agent`
            on both agent doors — the extractor runs under the agent's identity."
        principal_id:
          type: string
          example: agent_V1StGXR8Z5jdHi6B
        outcome:
          type: string
          enum:
            - created
            - superseded
            - skipped
            - retracted
          description: What the write resolved to. `created` is a distinct fact, `superseded` is the same fact
            changed (the top match was invalidated and replaced), `skipped` is a fact already known,
            `retracted` is a fact that stopped holding with nothing replacing it. Open set — new
            outcomes may be added in minor releases; clients must tolerate unknown values.
          example: created
        similarity:
          type: number
          nullable: true
          description: The cosine similarity the outcome was decided against — the top match's, or the
            declared target's when `declared` is true, where it decides nothing and only records how
            far apart the two statements were. Null when there was nothing to compare against, when
            the content could not be embedded, and on a `retracted` outcome, which compares nothing.
          example: 0.97
        declared:
          type: boolean
          description: Whether the write named the memory it replaced (`supersedes` on create) instead of the
            thresholds choosing one. Always false on a `created`, `skipped` or `retracted` outcome.
          example: false
        created_at:
          type: string
          format: date-time
    PrincipalType:
      type: string
      enum:
        - user
        - api_key
        - agent
        - automation
        - approval
        - trigger
        - system
        - eval
        - decider
        - ingestion_rule
        - memory_rule
        - playbook_version
      description: What kind of principal acted. `user` and `api_key` are authenticated callers, and the
        id is the user's (`user_…`) or the key's own (`key_…`), so a record names which key acted
        rather than its owner. `agent` is an agent writing under its own identity (`agent_…`).
        `automation` is the task engine acting on a dispatch outcome and `approval` an approval
        resolution; neither carries an id. `trigger` is a trigger firing under its own `policy_ids`
        (`trg_…`). `system` is the platform itself, with an id naming the mechanism
        (`retention_sweep`, `zero_retention`). `eval`, `decider`, `ingestion_rule`, `memory_rule`
        and `playbook_version` are that resource's work running under its own `policy_ids` when
        nobody started it, the id its own.
      example: user
    StoredError:
      type: object
      description: Why a resource's work failed, in the shape of an error response's `error` without
        `hint`. Every `error` field a resource records carries it, so `code` can be read without
        first checking the type of `error`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A key from the server's ERROR_CODES registry, documented on the Error Codes page.
            `INTERNAL_ERROR`, with the message `Internal Server Error`, records an unexpected
            failure whose detail reaches the server log only.
          example: AI_PROVIDER_ERROR
        message:
          type: string
          example: "Provider returned 402: insufficient credits"
        meta:
          type: object
          additionalProperties: true
          description: The failure's own structured context, when it names any.
    UsageTotals:
      type: object
      description: >
        Token counts and cost for one slice of the meter. Tokens and cost only: a `compute_second`
        or `gb_day` meter is reported by the aggregate's `components` array.


        The three input dimensions partition the prompt — `input_tokens` = `uncached_input_tokens` +
        `cached_tokens` + `cache_write_tokens` — and are separate because they are separately
        priced. Note that the `input_tokens` **component** on a usage event is the uncached figure
        alone; here `input_tokens` is the whole prompt.
      properties:
        cost_usd:
          type: number
          nullable: true
          description: Sum of priced component costs; null when nothing in the slice was priced. Always null
            at step altitude — the ledger prices one event per generation at write time, and a price
            read back per step would disagree with it after any price change.
        input_tokens:
          type: integer
          description: Full prompt tokens, reconstructed from the components.
        uncached_input_tokens:
          type: integer
          description: Prompt tokens priced at the plain input rate — the prompt minus cache reads and cache
            writes.
        output_tokens:
          type: integer
        cached_tokens:
          type: integer
          description: Prompt tokens served from the provider's prompt cache.
        cache_write_tokens:
          type: integer
          description: Prompt tokens written into the provider's prompt cache.
        reasoning_tokens:
          type: integer
          description: A non-billable subset of `output_tokens`, reported where the provider breaks it out.
    MetadataBag:
      type: object
      description: >-
        Caller-owned annotations on a resource, stored as the object they were written as: the types
        a value was written with are the types a read returns, so a filter can ask an ordering
        question about a number. Unlike other body fields, keys are stored and returned verbatim in
        the casing supplied — they are not converted between snake_case and camelCase.


        No key is reserved, and that is the point: every piece of state the platform owns lives in
        its own typed column, so nothing written here reaches platform state. The platform never
        reads the bag — it is not an IAM context, not a policy input and not part of a prompt —
        which is what separates it from a tag bag.
      example:
        author: John
        revision: 2
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_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"
    PayloadTooLarge:
      description: "`REQUEST_REJECTED` — the request body is over the size the body parser accepts"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionUnavailable:
      description: The deployment's admission service is asked about this write and did not answer —
        `ADMISSION_UNAVAILABLE`; the write did not happen
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionRefused:
      description: The deployment's admission service refused this write — answered under the service's
        own `4xx` status, with its `code` (matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`, not necessarily
        an `ERROR_CODES` key), `message` and `meta`; the write did not happen. A status this
        operation also declares on its own is documented there
      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"
