# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/conversations.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/conversations.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Conversations API
  version: 1.0.0
  description: >-
    Conversations: the durable message threads a session records into, and the transcript reads and
    writes over them. 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: Conversations
    description: Manage conversations
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/conversations:
    get:
      tags:
        - Conversations
      summary: List conversations
      description: Returns all conversations in the project named in the path.
      operationId: listConversations
      parameters:
        - name: actor_id
          in: query
          required: false
          description: Only conversations owned by this actor (their `actor_id`); message authorship does not
            match.
          schema:
            type: string
            example: actor_V1StGXR8Z5jdHi6B
        - $ref: "#/components/parameters/TagsQuery"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of conversations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ConversationRecord"
        "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"
    post:
      tags:
        - Conversations
      summary: Create a conversation
      description: Creates a new conversation in the project named in the path.
      operationId: createConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                status:
                  type: string
                  enum:
                    - open
                    - closed
                  default: open
                  description: Initial conversation status
                name:
                  type: string
                  nullable: true
                  description: Optional name for the conversation
                actor_id:
                  x-naturali-ref: actors
                  type: string
                  nullable: true
                  description: Actor ID to associate with this conversation
                  example: actor_V1StGXR8Z5jdHi6B
                retrieval:
                  type: string
                  enum:
                    - embed
                    - none
                    - null
                  nullable: true
                  description: Whether this conversation's turns are embedded for vector retrieval. Turns are stored
                    and chunked either way, so `none` leaves them readable and reachable by
                    full-text search without paying for an embedding. `null` (the default) inherits
                    the project's `default_conversation_retrieval`.
      responses:
        "201":
          description: Conversation created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationRecord"
        "400":
          description: Invalid request body
          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":
          $ref: "#/components/responses/ProjectNotFound"
        "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}/conversations/{conversation_id}:
    get:
      tags:
        - Conversations
      summary: Get a conversation by ID
      description: Returns a conversation by its ID
      operationId: getConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Conversation found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationRecord"
        "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: Conversation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - Conversations
      summary: Update a conversation
      description: Updates the status of a conversation
      operationId: updateConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                status:
                  type: string
                  enum:
                    - open
                    - closed
                  description: New conversation status
                name:
                  type: string
                  nullable: true
                  description: New conversation name
                retrieval:
                  type: string
                  enum:
                    - embed
                    - none
                    - null
                  nullable: true
                  description: Whether this conversation's turns are embedded for vector retrieval. Turns are stored
                    and chunked either way, so `none` leaves them readable and reachable by
                    full-text search without paying for an embedding. `null` (the default) inherits
                    the project's `default_conversation_retrieval`. Switching it on embeds the turns
                    already in the conversation, so the whole conversation becomes retrievable
                    rather than only what is said next.
      responses:
        "200":
          description: Conversation updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationRecord"
        "400":
          description: Invalid request body
          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: Conversation 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"
    delete:
      tags:
        - Conversations
      summary: Delete a conversation
      description: Deletes a conversation by its ID
      operationId: deleteConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      responses:
        "204":
          description: Conversation deleted
        "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: Conversation 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}/conversations/{conversation_id}/messages:
    get:
      tags:
        - Conversations
      summary: List conversation messages
      description: Returns all messages (documents) attached to a conversation, ordered by position
      operationId: listConversationMessages
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
        - name: order
          in: query
          required: false
          description: Sort direction by position; `desc` reads the transcript from its end.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of messages
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ConversationMessageRecord"
        "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: Conversation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - Conversations
      summary: Add a message to a conversation
      description: Creates a document from the message text and attaches it to the conversation at the
        given position. If position is omitted, it is appended at the end.
      operationId: addConversationMessage
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
                - role
              additionalProperties: false
              properties:
                message:
                  type: string
                  description: Message text content to add to the conversation
                  example: Hello, how can I help you?
                role:
                  type: string
                  enum:
                    - user
                    - assistant
                  description: Role of the message sender
                  example: user
                actor_id:
                  x-naturali-ref: actors
                  type: string
                  nullable: true
                  description: Optional actor ID to associate with this message (user identity)
                  example: actor_V1StGXR8Z5jdHi6B
                position:
                  type: integer
                  description: Zero-based position. Defaults to MAX+1 (append).
                  example: 0
                metadata:
                  description: "Caller-owned annotations on the message (e.g. a phone number, a channel), stored as
                    sent and returned verbatim. The platform does not read the bag, so nothing in it
                    reaches the model: a value the model should see belongs in `message`."
                  example:
                    phone: "5511999998888"
                    channel: whatsapp
                  allOf:
                    - $ref: "#/components/schemas/NullableMetadataBag"
      responses:
        "201":
          description: Message added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationMessageRecord"
        "400":
          description: Invalid request body
          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: Conversation or actor not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: CONVERSATION_POSITION_CONFLICT — another message took the requested position first.
          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}/conversations/{conversation_id}/generate:
    post:
      tags:
        - Conversations
      summary: Generate the next message in a conversation
      description: |
        Generates the next message using the specified actor's linked agent or chat.
        Background by default: returns `202 Accepted` with the generation's id
        once its record exists, and the reply lands as a new ConversationMessage
        when it completes — poll `GET /v1/projects/{project_id}/generations/{generation_id}` or
        `GET /v1/projects/{project_id}/conversations/{conversation_id}/messages` for it.
        Pass `?wait=true` to block and receive the result inline. On
        `completed`, the reply is persisted as a new ConversationMessage
        authored by that actor. On `requires_action`, nothing is persisted; the
        caller must submit tool outputs via the Agents module and re-invoke
        generate — so a flow using client tools should pass `?wait=true`.
      operationId: generateConversationMessage
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
        - name: wait
          in: query
          required: false
          x-naturali-tool-forced: true
          description: When omitted or `false` (default), the 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: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
              additionalProperties: false
              properties:
                agent_id:
                  x-naturali-ref: agents
                  type: string
                  description: ID of the agent that will produce the next message.
                model:
                  type: string
                  description: Optional model override.
                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 and keys are never case-converted, so they
                    round-trip exactly as sent. An invalid or colliding key is rejected with `400
                    INVALID_TOOL_CONTEXT_KEY`.
      responses:
        "200":
          description: "Generation completed 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, so `generation_id` is pollable via `GET
            /v1/projects/{project_id}/generations/{generation_id}`; the reply is persisted as a
            ConversationMessage when it completes.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - conversation_id
                  - generation_id
                  - trace_id
                properties:
                  status:
                    type: string
                    enum:
                      - accepted
                    example: accepted
                  conversation_id:
                    type: string
                    example: conv_V1StGXR8Z5jdHi6B
                  generation_id:
                    type: string
                    example: gen_V1StGXR8Z5jdHi6B
                  trace_id:
                    type: string
                    example: trace_V1StGXR8Z5jdHi6B
        "400":
          description: Invalid request
          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: Conversation or actor not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: PROJECT_PAUSED — the project is paused, so nothing new starts in it; `error.meta`
            carries `paused_at` and `pause_reason`.
          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":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/conversations/{conversation_id}/messages/{document_id}:
    delete:
      tags:
        - Conversations
      summary: Remove a message from a conversation
      description: Removes a document from a conversation
      operationId: removeConversationMessage
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
        - name: document_id
          in: path
          required: true
          description: Document ID
          schema:
            type: string
            example: doc_V1StGXR8Z5jdHi6B
      responses:
        "204":
          description: Message removed
        "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: Conversation or message 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}/conversations/{conversation_id}/tags:
    get:
      tags:
        - Conversations
      summary: Get conversation tags
      description: Returns all tags attached to the conversation
      operationId: getConversationTags
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Conversation tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "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: Conversation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      tags:
        - Conversations
      summary: Replace conversation tags
      description: Replaces all tags on the conversation with the provided tags
      operationId: replaceConversationTags
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags replaced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "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: Conversation 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"
    patch:
      tags:
        - Conversations
      summary: Merge conversation tags
      description: Merges provided tags into the conversation's existing tags (existing tags are preserved
        unless overridden)
      operationId: mergeConversationTags
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: string
            example: conv_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags merged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "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: Conversation 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"
components:
  schemas:
    ConversationRecord:
      type: object
      properties:
        id:
          type: string
          description: Conversation ID
          example: conv_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          description: Project ID
          example: proj_V1StGXR8Z5jdHi6B
        name:
          type: string
          nullable: true
          description: Optional human-readable name for the conversation.
        status:
          type: string
          enum:
            - open
            - closed
          description: Conversation status
          example: open
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        actor_id:
          x-naturali-ref: actors
          type: string
          nullable: true
          description: Actor ID associated with this conversation
          example: actor_V1StGXR8Z5jdHi6B
        tags:
          $ref: "#/components/schemas/TagBag"
        retrieval:
          type: string
          enum:
            - embed
            - none
            - null
          nullable: true
          description: Whether this conversation's turns are embedded for vector retrieval. Turns are stored
            and chunked either way, so `none` leaves them readable and reachable by full-text search
            without paying for an embedding. `null` (the default) inherits the project's
            `default_conversation_retrieval`.
    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...
    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
    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
    GenerateConversationMessageResponse:
      oneOf:
        - $ref: "#/components/schemas/GenerateConversationMessageCompleted"
        - $ref: "#/components/schemas/GenerateConversationMessageRequiresAction"
      discriminator:
        propertyName: status
        mapping:
          completed: "#/components/schemas/GenerateConversationMessageCompleted"
          requires_action: "#/components/schemas/GenerateConversationMessageRequiresAction"
    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`.
    NullableMetadataBag:
      type: object
      nullable: true
      description: "A `MetadataBag` on a request field where `null` is meaningful: a full-replacement
        update that clears the bag. A record whose bag is unset leaves the field out."
      example:
        author: John
        revision: 2
    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
    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
    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
  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"
