# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/sessions.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/sessions.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Sessions API
  version: 1.0.0
  description: >-
    Sessions: durable, resumable dialogues with an agent — messages, generations, tool outputs,
    forks and tags. 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: Sessions
    description: Manage agent sessions
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/sessions:
    post:
      tags:
        - Sessions
      summary: Create a session
      description: >
        Creates a new session for the specified agent, along with the underlying conversation, so
        the caller only needs this single call to start interacting with the agent. No actor is
        created: pass `actor_id` to attach an existing actor as the session's end user. When it is
        omitted the session has no actor, and generations in it carry no end-user attribution — they
        are not billed to an actor in the usage meter and they match no `actor`-scoped quota.
      operationId: createSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSessionRequest"
      responses:
        "201":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: An open session already exists for this actor (single_session_per_actor is enabled)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: SINGLE_SESSION_CONFLICT
                  message: An open session already exists for this actor.
                  hint: The agent allows one open session per actor. Reuse the session named in `meta.session_id`, or
                    close it first.
                  meta:
                    session_id: sess_abc123
        "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"
    get:
      tags:
        - Sessions
      summary: List sessions
      description: Returns sessions the caller can access, optionally filtered by agent, actor and status.
      operationId: listSessions
      parameters:
        - name: agent_id
          in: query
          required: false
          description: Filter by agent public ID
          schema:
            type: string
            example: agent_V1StGXR8Z5jdHi6B
        - name: actor_id
          in: query
          required: false
          description: Filter by actor public ID
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by session 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:
                - open
                - closed
                - expired
          style: form
          explode: true
        - $ref: "#/components/parameters/TagsQuery"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Paginated list of sessions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SessionRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/sessions/{session_id}:
    get:
      tags:
        - Sessions
      summary: Get a session
      description: Returns details of a single session, including a `usage` roll-up of what its
        generations cost. The listing omits `usage`; for a window, a split by day or model, or one
        end user across every session, narrow `GET /v1/projects/{project_id}/usage` with
        `session_id` / `actor_id` instead.
      operationId: getSession
      parameters:
        - $ref: "#/components/parameters/SessionId"
      responses:
        "200":
          description: Session details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - Sessions
      summary: Update a session
      description: Updates the session name and/or status.
      operationId: updateSession
      parameters:
        - $ref: "#/components/parameters/SessionId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSessionRequest"
      responses:
        "200":
          description: Updated session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionRecord"
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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"
    delete:
      tags:
        - Sessions
      summary: Delete a session
      description: >
        Deletes the session and its underlying conversation and messages. The session's actor is not
        deleted. Generations and traces produced by the session are not deleted either, since they
        are not linked to the session or conversation.
      operationId: deleteSession
      parameters:
        - $ref: "#/components/parameters/SessionId"
      responses:
        "204":
          description: Session deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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}/sessions/{session_id}/messages:
    post:
      tags:
        - Sessions
      summary: Add a user message
      description: >
        Saves a user message to the session. When `auto_generate` is enabled on the session and no
        generation is currently in progress, generation is triggered automatically and the response
        is the generated turn, the same body `?wait=true` generate answers. Otherwise returns the
        saved user message.
      operationId: addSessionMessage
      parameters:
        - $ref: "#/components/parameters/SessionId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddSessionMessageRequest"
      responses:
        "200":
          description: Duplicate request — original message returned (idempotency_key matched)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddSessionMessageSaved"
        "201":
          description: User message saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddSessionMessageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a message in this session
            sent from a different request. No message is saved."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: SESSION_EXPIRED — the session outlived its time-to-live and takes no more messages.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          description: "`QUOTA_EXCEEDED`: the session auto-generates and an `enforce`-mode generation quota is
            exhausted. `error.meta` carries `quota_id`, `metric`, `limit`, `window` and `resets_at`,
            with a `Retry-After` header. The message is saved. A session with
            `message_delay_seconds` answers `201` before the quota is read."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/sessions/{session_id}/generate:
    post:
      tags:
        - Sessions
      summary: Trigger agent generation
      description: >
        Triggers the agent to generate a response based on the current conversation. Background by
        default: returns `202 Accepted` with the generation's id once its record exists. Pass
        ?wait=true to block and receive the assistant reply (or a requires_action status if the
        agent needs client tool outputs) in the response. Pass `stream: true` in the body to receive
        the turn's events as SSE, one frame per step and tool call, until it settles; `stream: true`
        with `?wait=false` is `400`.
      operationId: generateSessionResponse
      parameters:
        - $ref: "#/components/parameters/SessionId"
        - name: wait
          in: query
          required: false
          x-naturali-tool-forced: true
          description: When omitted or `false` (default), generation runs in the background and `202 Accepted`
            is returned immediately. Pass `true` to block until the generation settles and receive
            the result. A tool call, `builtin` or MCP, always waits.
          schema:
            type: boolean
            default: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateSessionRequest"
      responses:
        "200":
          description: "Agent reply or requires_action (only when `?wait=true`), or the turn's event stream
            (with `stream: true`)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateConversationMessageResponse"
            text/event-stream:
              schema:
                type: string
                description: >
                  With `stream: true`: first an `event: accepted` frame whose `data` is the `202`
                  body, then the generation's events as on `GET
                  /v1/projects/{project_id}/generations/{generation_id}/events?stream=true`, one
                  `event: progress` frame per row, ending with `data: [DONE]` when the generation
                  settles. Step content needs `traces:GetTrace` on the trace; without it the frames
                  carry the rows only (`step` is null).
        "202":
          description: "Generation accepted and running in the background (default, when `wait` is omitted or
            `false`). The generation record already exists: poll `GET
            /v1/projects/{project_id}/generations/{generation_id}` for it."
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - session_id
                  - generation_id
                  - trace_id
                properties:
                  status:
                    type: string
                    enum:
                      - accepted
                  session_id:
                    type: string
                  generation_id:
                    type: string
                    example: gen_V1StGXR8Z5jdHi6B
                  trace_id:
                    type: string
                    example: trace_V1StGXR8Z5jdHi6B
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Generation already in progress
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: Session has expired due to inactivity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          description: "`QUOTA_EXCEEDED`: an `enforce`-mode generation quota is exhausted. `error.meta`
            carries `quota_id`, `metric`, `limit`, `window` and `resets_at`, with a `Retry-After`
            header. Only with `?wait=true`: a background call is answered `202` before the quota is
            read."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: >
            Upstream AI provider error (AI_PROVIDER_ERROR). The error `meta` includes the
            `generation_id` and `trace_id` of the failed generation for post-mortem debugging via
            GET /v1/projects/{project_id}/generations/{generation_id}.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/sessions/{session_id}/tool-outputs:
    post:
      tags:
        - Sessions
      summary: Submit tool outputs
      description: >
        Submits client tool outputs for a generation that returned requires_action. The agent
        continues its loop and returns the final or next requires_action result. A generation that
        did not run in the session's conversation is 404 (GENERATION_NOT_FOUND) and receives no
        outputs. Requires `generations:ResumeGeneration` on the generation in addition to
        `agents:SubmitSessionToolOutputs`; the resumed segment runs under the generation's stored
        authority held to the caller's.
      operationId: submitSessionToolOutputs
      parameters:
        - $ref: "#/components/parameters/SessionId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitSessionToolOutputsRequest"
      responses:
        "200":
          description: Generation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateConversationMessageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: >
            The generation is not paused on client tool calls
            (GENERATION_NOT_AWAITING_TOOL_OUTPUTS): it never paused, or its outputs were already
            submitted. Each pause accepts outputs once.
          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}/sessions/{session_id}/fork:
    post:
      tags:
        - Sessions
      summary: Fork a session
      description: >
        Branches a new session from a point in this session's history: same context, different
        continuation.


        The fork gets its own conversation whose messages **reference the same documents** as the
        parent rather than copying them, so there is one stored copy of the content and a retention
        purge erases it from both. Recorded tool results ride along on those messages and are
        **replayed** as model input on the fork's next turn — forking never re-invokes a tool, so
        exploring a "what if" cannot send an email or charge a card a second time. The consequence
        to accept is that a forked turn sees the tool data as it was, not as it is now.


        The fork is created **inert**: `auto_generate` is false and no generation is triggered.
        Drive it with the normal message and generate endpoints. The fork has no actor — attach one
        only if the branch is meant to be driven by the same end user, since
        `single_session_per_actor` agents allow one open session per actor.
      operationId: forkSession
      parameters:
        - $ref: "#/components/parameters/SessionId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkSessionRequest"
      responses:
        "201":
          description: Fork created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionRecord"
        "400":
          description: "`fork_at_position` names no message in the parent conversation, or `agent_id` is
            unknown or belongs to another project"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: VALIDATION_FAILED
                  message: fork_at_position 9 does not exist in the parent conversation.
                  hint: Fix the request and retry. Unknown fields are rejected outright, so compare the payload
                    against the operation in `/v1/openapi.json`; `meta` names the offending field
                    when the check can identify one.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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}/sessions/{session_id}/forks:
    get:
      tags:
        - Sessions
      summary: List a session's forks
      description: >
        Returns the sessions forked directly from this one. One level of lineage: a fork of a fork
        is listed under its own parent.
      operationId: listSessionForks
      parameters:
        - $ref: "#/components/parameters/SessionId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Paginated list of forks
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SessionRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/sessions/{session_id}/tags:
    get:
      tags:
        - Sessions
      summary: Get session tags
      description: Returns the session's tags object.
      operationId: getSessionTags
      parameters:
        - $ref: "#/components/parameters/SessionId"
      responses:
        "200":
          description: Session tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      tags:
        - Sessions
      summary: Replace session tags
      description: Replaces all tags on the session.
      operationId: replaceSessionTags
      parameters:
        - $ref: "#/components/parameters/SessionId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Updated tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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"
    patch:
      tags:
        - Sessions
      summary: Merge session tags
      description: Merges the provided tags into the session's existing tags.
      operationId: mergeSessionTags
      parameters:
        - $ref: "#/components/parameters/SessionId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Updated tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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"
components:
  schemas:
    SessionRecord:
      type: object
      properties:
        id:
          type: string
          description: Session public ID
          example: sess_V1StGXR8Z5jdHi6B
        agent_id:
          x-naturali-ref: agents
          type: string
          description: |
            Agent public ID, kept after a shared agent is deleted by its owner.
          example: agent_V1StGXR8Z5jdHi6B
        conversation_id:
          x-naturali-ref: conversations
          type: string
          description: Underlying conversation public ID
          example: conv_V1StGXR8Z5jdHi6B
        status:
          type: string
          enum:
            - open
            - closed
            - expired
          example: open
        name:
          type: string
          nullable: true
          example: Support chat
        actor_id:
          x-naturali-ref: actors
          type: string
          nullable: true
          description: |
            Public ID of the user actor, or null when the session was created without one
          example: actor_V1StGXR8Z5jdHi6B
        tags:
          $ref: "#/components/schemas/TagBag"
        auto_generate:
          type: boolean
          default: false
          description: When true, automatically triggers generation after each user message (if no generation
            is in progress).
        generating_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the current generation started, or null if not generating.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        inactivity_ttl_seconds:
          type: integer
          default: 0
          description: Number of seconds of inactivity after which the session expires. 0 means the session
            never expires.
          example: 300
        message_delay_seconds:
          type: integer
          nullable: true
          default: null
          description: >
            Number of seconds to wait after the last user message before sending to the LLM. Acts as
            a debounce: each new message resets the timer. null or absent means no delay (immediate
            processing).
          example: 3
        max_context_messages:
          type: integer
          nullable: true
          default: null
          description: >
            Maximum number of recent conversation messages sent to the model on each generation.
            Takes precedence over the agent's `max_context_messages`; null defers to it. A fork
            keeps its parent's value.
          example: 20
        last_activity_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last activity on the session (message added or response generated).
        forked_from_session_id:
          x-naturali-ref: sessions
          type: string
          nullable: true
          description: >
            Public ID of the session this one was forked from, or null when it was not forked. Also
            null once that parent is deleted — a fork survives its parent and keeps its own history.
          example: sess_V1StGXR8Z5jdHi6B
        forked_from_position:
          type: integer
          nullable: true
          description: >
            The parent conversation position this session branched after, or null when it is not a
            fork or was forked at the tip.
          example: 7
        usage:
          allOf:
            - $ref: "#/components/schemas/UsageTotals"
          description: >-
            What the session's generations cost: token counts and `cost_usd` summed across every
            metered generation dispatched through it. Present on the single-session read; omitted
            from session and fork list responses.


            A fork is a session of its own, so it starts at zero rather than inheriting what the
            history it copied cost — summing `usage` across a session and its forks therefore never
            double-counts. Work the platform does around a session without a generation of its own
            (a memory extraction pass, for instance) is metered on the project, not here.
    ForkSessionRequest:
      type: object
      additionalProperties: false
      properties:
        fork_at_position:
          type: integer
          minimum: 0
          description: >
            The parent conversation `position` to branch after. Messages at positions 0..N are
            carried into the fork. Omit it to branch at the tip (the whole history).
          example: 7
        agent_id:
          x-naturali-ref: agents
          type: string
          description: >
            Agent the fork runs against. Defaults to the parent session's agent; overriding it is
            the point of forking — same context, a different agent or agent version. Must belong to
            the same project as the session being forked.
          example: agent_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: Optional name for the forked session
          example: retry with stricter system prompt
        tags:
          $ref: "#/components/schemas/TagBag"
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: >
            Overrides the parent's `tool_context` on the fork. Omit it and the fork inherits the
            parent's, so the branch is faithful to the run it came from.
    CreateSessionRequest:
      type: object
      required:
        - agent_id
      additionalProperties: false
      properties:
        agent_id:
          x-naturali-ref: agents
          type: string
          description: >
            Agent this session belongs to. With a credential scoped to a project, it may also be an
            agent another project shares with that project; the session is then that project's.
          example: agent_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: Optional session name
          example: Support chat
        tags:
          $ref: "#/components/schemas/TagBag"
        actor_id:
          x-naturali-ref: actors
          type: string
          description: >
            Optional public ID of an existing actor to use as the user actor. Actors are created
            separately (POST /actors); this field only links one. Omit it and the session has no end
            user, so its generations match no actor-scoped quota.
          example: actor_V1StGXR8Z5jdHi6B
        auto_generate:
          type: boolean
          default: false
          description: When true, automatically triggers generation after each user message.
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http`, `mcp`
            and `builtin` tool call in this session. The header name is the deployment's configured
            context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character
            is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not
            a valid HTTP header name, or two keys that map to the same header, are rejected with
            `400 INVALID_TOOL_CONTEXT_KEY`. `session_id`, `actor_id` and `actor_external_id` are
            server-derived and dropped from the stored bag, in any casing. Write-only: no read of a
            session returns it. It also does not outlive the session: closing or expiring it clears
            the bag."
        inactivity_ttl_seconds:
          type: integer
          default: 0
          description: Number of seconds of inactivity after which the session expires. 0 means the session
            never expires.
          example: 300
        message_delay_seconds:
          type: integer
          nullable: true
          default: null
          description: >
            Number of seconds to wait after the last user message before sending to the LLM. Acts as
            a debounce: each new message resets the timer. null or absent means no delay (immediate
            processing).
          example: 3
        max_context_messages:
          type: integer
          nullable: true
          minimum: 1
          default: null
          description: >
            Maximum number of recent conversation messages sent to the model on each generation,
            taking precedence over the agent's `max_context_messages`. null or absent defers to the
            agent.
          example: 20
    UpdateSessionRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          nullable: true
          description: Session name (set to null to clear)
        status:
          type: string
          enum:
            - open
            - closed
            - expired
          description: Session status
        auto_generate:
          type: boolean
          description: Enable or disable automatic generation after user messages.
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http`, `mcp`
            and `builtin` tool call in this session. The header name is the deployment's configured
            context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character
            is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not
            a valid HTTP header name, or two keys that map to the same header, are rejected with
            `400 INVALID_TOOL_CONTEXT_KEY`. `session_id`, `actor_id` and `actor_external_id` are
            server-derived and dropped from the stored bag, in any casing. Write-only: no read of a
            session returns it. It also does not outlive the session: closing or expiring it clears
            the bag."
        inactivity_ttl_seconds:
          type: integer
          description: >
            Number of seconds of inactivity after which the session expires. 0 means the session
            never expires. Updates the stored TTL; the inactivity clock continues from the last
            activity timestamp.
          example: 300
        message_delay_seconds:
          type: integer
          nullable: true
          description: >
            Number of seconds to wait after the last user message before sending to the LLM. Acts as
            a debounce: each new message resets the timer. Set to null to disable the delay.
          example: 3
        max_context_messages:
          type: integer
          nullable: true
          minimum: 1
          description: >
            Maximum number of recent conversation messages sent to the model on each generation,
            taking precedence over the agent's `max_context_messages`. Set to null to defer to the
            agent.
          example: 20
    AddSessionMessageRequest:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - message
          properties:
            message:
              type: string
              description: User message text
              example: Hello, how can I deploy my app?
            tool_context:
              type: object
              additionalProperties:
                type: string
              nullable: true
              description: Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http`, `mcp`
                and `builtin` tool call in this generation. The header name is the deployment's
                configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim —
                no character is re-cased. Keys are never case-converted — they round-trip exactly as
                sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.
            idempotency_key:
              type: string
              description: >
                Optional deduplication key scoped to this session. If a message with the same key
                already exists in the session, the original message is returned with HTTP 200 and no
                new message or generation is triggered. Reusing the key with a different `message`,
                `document_id` or `tool_context` is `409 IDEMPOTENCY_KEY_REUSED`.
              example: wamid.HBgLNTUxMTk4...
        - type: object
          additionalProperties: false
          required:
            - document_id
          properties:
            document_id:
              x-naturali-ref: documents
              type: string
              description: Public ID of a document used as the user message content.
            tool_context:
              type: object
              additionalProperties:
                type: string
              nullable: true
              description: Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http`, `mcp`
                and `builtin` tool call in this generation. The header name is the deployment's
                configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim —
                no character is re-cased. Keys are never case-converted — they round-trip exactly as
                sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.
            idempotency_key:
              type: string
              description: >
                Optional deduplication key scoped to this session. If a message with the same key
                already exists in the session, the original message is returned with HTTP 200 and no
                new message or generation is triggered. Reusing the key with a different `message`,
                `document_id` or `tool_context` is `409 IDEMPOTENCY_KEY_REUSED`.
              example: wamid.HBgLNTUxMTk4...
    AddSessionMessageSaved:
      type: object
      description: Message saved; auto-generate is off or a generation is already in progress.
      properties:
        role:
          type: string
          enum:
            - user
        content:
          type: string
        document_id:
          x-naturali-ref: documents
          type: string
          nullable: true
    AddSessionMessageResponse:
      anyOf:
        - $ref: "#/components/schemas/AddSessionMessageSaved"
        - $ref: "#/components/schemas/GenerateConversationMessageResponse"
    GenerateSessionRequest:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Optional model override
          example: gpt-4o
        stream:
          type: boolean
          default: false
          x-naturali-tool-unsupported: true
          description: When true, the response is the turn's event stream (SSE) at step granularity. Implies
            waiting; `?wait=false` with it is `400`.
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http`, `mcp`
            and `builtin` tool call in this generation. The header name is the deployment's
            configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no
            character is re-cased. Keys are never case-converted — they round-trip exactly as sent.
            An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.
    SubmitSessionToolOutputsRequest:
      type: object
      required:
        - generation_id
        - tool_outputs
      additionalProperties: false
      properties:
        generation_id:
          x-naturali-ref: generations
          type: string
          description: The generation ID from the requires_action response
        tool_outputs:
          type: array
          items:
            type: object
            required:
              - tool_call_id
              - output
            additionalProperties: false
            properties:
              tool_call_id:
                type: string
              output:
                description: The tool output value
    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`.
    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.
    GenerateConversationMessageResponse:
      oneOf:
        - $ref: "#/components/schemas/GenerateConversationMessageCompleted"
        - $ref: "#/components/schemas/GenerateConversationMessageRequiresAction"
      discriminator:
        propertyName: status
        mapping:
          completed: "#/components/schemas/GenerateConversationMessageCompleted"
          requires_action: "#/components/schemas/GenerateConversationMessageRequiresAction"
    GenerateConversationMessageCompleted:
      type: object
      required:
        - status
        - content
        - message
        - generation_id
        - trace_id
      properties:
        status:
          type: string
          enum:
            - completed
          description: Indicates generation finished successfully.
        content:
          type: string
          description: >
            The AI-generated text of the reply. This is the canonical field for the assistant's
            response text.
          example: Hello! How can I help you today?
        message:
          description: The stored assistant message, the record `GET
            /v1/projects/{project_id}/conversations/{conversation_id}/messages` lists at its
            `position`. Its `document_id` addresses it.
          allOf:
            - $ref: "#/components/schemas/ConversationMessageRecord"
        generation_id:
          x-naturali-ref: generations
          type: string
          description: ID of the underlying generation record.
          example: gen_V1StGXR8Z5jdHi6B
        trace_id:
          x-naturali-ref: traces
          type: string
          description: Trace ID for observability.
          example: trace_V1StGXR8Z5jdHi6B
        model:
          type: string
          description: Model used for generation.
          example: gpt-4o
    ConversationMessageRecord:
      type: object
      properties:
        document_id:
          x-naturali-ref: documents
          type: string
          description: Document ID
          example: doc_V1StGXR8Z5jdHi6B
        role:
          type: string
          enum:
            - user
            - assistant
            - system
          description: Role of the message sender
          example: user
        actor_id:
          x-naturali-ref: actors
          type: string
          nullable: true
          description: Optional actor ID associated with this message
          example: actor_V1StGXR8Z5jdHi6B
        agent_id:
          x-naturali-ref: agents
          type: string
          nullable: true
          description: Optional agent ID that generated this message (set for assistant messages produced by
            generate)
          example: agent_V1StGXR8Z5jdHi6B
        position:
          type: integer
          description: Zero-based position in the conversation
          example: 0
        metadata:
          description: Optional structured metadata attached to the message
          example:
            phone: "5511999998888"
            channel: whatsapp
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
        content:
          type: string
          nullable: true
          description: Full text content of the message
        idempotency_key:
          type: string
          nullable: true
          description: The idempotency key the message was posted with, null when none was sent. A channel
            that posts each inbound message under its provider's message id finds the transcript row
            for that message by this key.
          example: wamid.HBgLNTUxMTk4...
    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
    GenerateConversationMessageRequiresAction:
      type: object
      required:
        - status
        - generation_id
        - trace_id
        - required_action
      properties:
        status:
          type: string
          enum:
            - requires_action
          description: >
            Indicates the agent requires tool-call outputs before it can produce a reply. No message
            is persisted yet.
        generation_id:
          x-naturali-ref: generations
          type: string
          description: ID of the paused generation. Pass to the tool-outputs endpoint.
          example: gen_V1StGXR8Z5jdHi6B
        trace_id:
          x-naturali-ref: traces
          type: string
          description: Trace ID for observability.
          example: trace_V1StGXR8Z5jdHi6B
        required_action:
          type: object
          description: Tool-call information the client must resolve.
          properties:
            type:
              type: string
              enum:
                - submit_tool_outputs
            tool_calls:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  tool_name:
                    type: string
                  args:
                    type: object
    TagBag:
      type: object
      additionalProperties:
        type: string
      x-cli-flag-name: tags
      description: >-
        Key-value labels on a resource. A flat object of string values — an array, a nested object
        or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and
        stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB
        containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM
        `iam:ResourceTag/<key>` condition.


        Keys beginning `system.` are reserved: the platform writes them to record which
        conversation, actor, agent and role a row came from, and a write naming one is refused with
        `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.


        The bag is bounded, because every pair reaches the IAM context of every access check on the
        resource: at most 50 keys, each key at most 128 characters and each value at most 256. A
        write past a bound — including a merge that would grow the stored bag past the key count —
        is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys
        are the platform's and do not count against the 50.
      example:
        team: finance
        env: prod
    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.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    SessionId:
      name: session_id
      in: path
      required: true
      description: Session public ID
      schema:
        type: string
        example: sess_V1StGXR8Z5jdHi6B
    TagsQuery:
      name: tags
      in: query
      required: false
      description: >
        Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain
        colons). Repeat the parameter for several pairs; **all** must be present with exactly that
        value.
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
        - env:prod
    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
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: The request's deduplication key. Equivalent to `idempotency_key` in the request body;
        sending both with different values is `400 VALIDATION_FAILED`. A non-empty string of at most
        255 characters.
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: discord-msg-1234567890
  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"
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: The credential is scoped to a different project, or the caller's role in the project
        does not carry this action.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: The resource does not exist (existence is not leaked).
      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"
    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"
    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"
