# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/deciders.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/deciders.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Deciders API
  version: 1.0.0
  description: >-
    Deciders: versioned question sets answered against a caller's input, and the append-only
    decisions they produce, in the question and answer shapes of OpenAI's Decisions API. Every
    answer is confined to the answer space its question declares, and every decision names the
    question-set version it was answered under, or carries the questions it was sent with. A decider
    is answered by a tool-less agent or by an http or pipeline tool. 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: Deciders
    description: Manage deciders and request decisions from them
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/deciders:
    get:
      tags:
        - Deciders
      summary: List deciders
      description: Returns the deciders defined in a project, newest first.
      operationId: listDeciders
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of deciders
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Decider"
        "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:
        - Deciders
      summary: Create a decider
      description: "Creates a decider at version 1: a named question set and the backend that answers it,
        exactly one of `agent_id` and `tool_id`. Every question declares a finite answer space,
        validated here. The backend must be in the decider's project. An agent must carry no tool
        surface — no tool binding left active by `active_tool_ids` and no
        `knowledge_config.write_memory_store_id` — or the create is refused with `400
        DECIDER_AGENT_NOT_TOOL_LESS`. A tool must run server-side with no `action` (not `client` or
        `mcp`; a `builtin` tool names its `action` in `preset_parameters`) and must not pin `input`
        or `questions` there, or the create is refused with `400 DECIDER_TOOL_NOT_CALLABLE`. A
        duplicate `name` in the project is `409 NAME_CONFLICT`."
      operationId: createDecider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDeciderRequest"
      responses:
        "201":
          description: Decider created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decider"
        "400":
          description: Bad request — invalid questions, an unknown or tool-bearing agent
          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"
        "409":
          description: A decider with this name already exists in the project
          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}/deciders/{decider_id}:
    get:
      tags:
        - Deciders
      summary: Get a decider
      description: Returns a decider with its current question set and version.
      operationId: getDecider
      parameters:
        - $ref: "#/components/parameters/DeciderId"
      responses:
        "200":
          description: The decider
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decider"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Decider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - Deciders
      summary: Update a decider
      description: Updates any of `name`, `description`, the backend and `questions`. Naming `agent_id` or
        `tool_id` replaces the current backend; naming both is `400`. Only a change to `questions`
        archives a new version; a rename, a new backend or a rewrite of the questions the decider
        already holds leaves `version` where it is. A new backend is held to the same rules as on
        create.
      operationId: updateDecider
      parameters:
        - $ref: "#/components/parameters/DeciderId"
        - $ref: "#/components/parameters/IfMatchVersion"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDeciderRequest"
      responses:
        "200":
          description: Decider updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decider"
        "400":
          description: Bad request — invalid questions, an unknown or tool-bearing agent
          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: Decider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          $ref: "#/components/responses/VersionConflict"
        "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:
        - Deciders
      summary: Delete a decider
      description: Deletes a decider and its version archive. Its decisions remain and keep naming the
        decider's ID.
      operationId: deleteDecider
      parameters:
        - $ref: "#/components/parameters/DeciderId"
      responses:
        "204":
          description: Decider 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: Decider 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}/deciders/{decider_id}/versions:
    get:
      tags:
        - Deciders
      summary: List a decider's versions
      description: Returns the decider's archived question sets, newest first. A version is written on
        create and on every write that changes `questions`.
      operationId: listDeciderVersions
      parameters:
        - $ref: "#/components/parameters/DeciderId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of decider versions, newest first
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/DeciderVersion"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Decider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/deciders/{decider_id}/versions/{version}:
    get:
      tags:
        - Deciders
      summary: Fetch an archived decider version
      description: Returns the question set a version held. A decision names the `decider_version` it was
        answered under, so this is how its criteria are read after the decider has changed.
      operationId: getDeciderVersion
      parameters:
        - $ref: "#/components/parameters/DeciderId"
        - $ref: "#/components/parameters/Version"
      responses:
        "200":
          description: Archived decider version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeciderVersion"
        "400":
          description: Bad request — version is not a positive integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/deciders/{decider_id}/versions/{version}/restore:
    post:
      tags:
        - Deciders
      summary: Restore an archived decider version
      description: Writes an archived question set back as the decider's live one, which archives it again
        as a new version rather than rewinding the counter. Restoring the question set the decider
        already holds is a no-op.
      operationId: restoreDeciderVersion
      parameters:
        - $ref: "#/components/parameters/DeciderId"
        - $ref: "#/components/parameters/Version"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestoreDeciderVersionRequest"
      responses:
        "200":
          description: The decider, at its new version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decider"
        "400":
          description: Bad request — version is not a positive integer
          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: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          $ref: "#/components/responses/VersionConflict"
        "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}/deciders/{decider_id}/decisions:
    post:
      tags:
        - Deciders
      summary: Request a decision
      description: >-
        Evaluates the decider against `input` and records the decision. The questions come from the
        decider, never from the request, so a call site can only supply what is judged. To send the
        questions with the request, use `POST /v1/projects/{project_id}/decisions`.


        Everything that can refuse the request is checked before the decision is written, so a
        refusal is a `4xx` and never a polled failure: the agent's tool surface (`400
        DECIDER_AGENT_NOT_TOOL_LESS`), a tool that cannot answer (`400 DECIDER_TOOL_NOT_CALLABLE`),
        a paused project (`409 PROJECT_PAUSED`) and, for an agent, quota admission (`429
        QUOTA_EXCEEDED`).


        A tool backend is called with `{ input, questions }` and must answer `{ answers: [{ name,
        probability | choice | score, probabilities?, confidence? }] }`, the request and response of
        OpenAI's Decisions API; an answer outside that contract fails the decision with
        `DECISION_ANSWER_INVALID`.


        With `wait: false`, the default, the answer is `201` with the decision `queued`; poll `GET
        /v1/projects/{project_id}/decisions/{decision_id}` or subscribe to `decisions.completed` and
        `decisions.failed`. With `wait: true` it is `201` with the decision settled.
      operationId: createDecision
      parameters:
        - $ref: "#/components/parameters/DeciderId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDecisionRequest"
      responses:
        "201":
          description: The decision — `queued`, or settled when `wait` is true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decision"
        "400":
          description: Bad request — a missing or malformed input, a non-object metadata bag, or a
            tool-bearing agent
          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: Decider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The project is paused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          description: A generation quota is exhausted
          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}/decisions:
    post:
      tags:
        - Deciders
      summary: Request a decision with inline questions
      description: >-
        Evaluates `questions` sent with the request against `input`, answered by the agent or tool
        the request names (exactly one of `agent_id` and `tool_id`, held to the same rules as a
        decider's backend), and records the decision with its questions. The request and answers are
        those of OpenAI's Decisions API, with the backend in place of `model`.


        No decider names the questions, so the decision carries them in `questions` and has no
        `decider_id` or `decider_version`. Admission, `wait` and the tool contract are those of
        `POST /v1/projects/{project_id}/deciders/{decider_id}/decisions`.
      operationId: createInlineDecision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateInlineDecisionRequest"
      responses:
        "201":
          description: The decision — `queued`, or settled when `wait` is true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decision"
        "400":
          description: Bad request — invalid questions or input, no backend or both, or a backend that cannot
            answer
          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"
        "409":
          description: The project is paused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          description: A generation quota is exhausted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    get:
      tags:
        - Deciders
      summary: List decisions
      description: Returns the decisions in a project, newest first.
      operationId: listDecisions
      parameters:
        - name: decider_id
          in: query
          description: Only decisions requested from this decider
          schema:
            type: string
            example: dcd_V1StGXR8Z5jdHi6B
        - name: status
          in: query
          required: false
          description: Only decisions in these statuses. Repeat the parameter to OR values. A value outside
            the enum, empty string included, is a `400`.
          schema:
            type: array
            items:
              type: string
              enum:
                - queued
                - running
                - completed
                - failed
          style: form
          explode: true
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of decisions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Decision"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/decisions/{decision_id}:
    get:
      tags:
        - Deciders
      summary: Get a decision
      description: "Returns a decision. Poll it after a `wait: false` request until `status` is
        `completed` or `failed`."
      operationId: getDecision
      parameters:
        - name: decision_id
          in: path
          required: true
          description: The decision ID
          schema:
            type: string
            example: dec_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: The decision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decision"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Decision not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    DeciderChoice:
      type: object
      additionalProperties: false
      required:
        - value
        - description
      properties:
        value:
          type: string
          description: What a `choice` answer carries; unique within the question
          example: billing
        description:
          type: string
          example: Payments, invoices and refunds.
    DeciderLevel:
      type: object
      additionalProperties: false
      required:
        - label
        - description
      properties:
        label:
          type: string
          example: Workaround available
        description:
          type: string
          example: A task fails, but another way works.
    DeciderQuestion:
      type: object
      additionalProperties: false
      required:
        - type
        - name
        - instructions
      description: One question and its answer space. A `predicate` checks a condition and is answered
        with the probability it holds. A `choice` selects one of `choices` (2 to 20, in the order
        the model is shown them). A `score` rates against ordered `levels` (2 to 20); its answer is
        a level index, or a value between two when a tool weighs them.
      properties:
        type:
          type: string
          enum:
            - predicate
            - choice
            - score
          example: choice
        name:
          type: string
          description: Names the question's answer. Unique within the set; starts with a letter or underscore
            and holds only letters, digits and underscores (at most 64).
          example: department
        instructions:
          type: string
          description: What to judge
          example: Which department should handle this complaint?
        choices:
          type: array
          description: A `choice` question's options; required for `choice` only
          items:
            $ref: "#/components/schemas/DeciderChoice"
        levels:
          type: array
          description: A `score` question's ordered levels; required for `score` only
          items:
            $ref: "#/components/schemas/DeciderLevel"
    DeciderQuestions:
      type: array
      minItems: 1
      maxItems: 20
      description: The questions, in the order the model is shown them.
      items:
        $ref: "#/components/schemas/DeciderQuestion"
      example:
        - type: choice
          name: department
          instructions: Which department should handle this complaint?
          choices:
            - value: billing
              description: Payments, invoices and refunds.
            - value: technical
              description: Problems using the product.
        - type: predicate
          name: needs_human
          instructions: Must a person read this before any automated reply?
    DecisionInput:
      description: "What is judged, not stored: a string; a list of `user` messages whose `content` is a
        string or `input_text` and `input_image` parts (an image as a base64 data URL); or any other
        JSON value, which an agent is shown as indented JSON. An array of objects carrying `role` is
        read as messages."
      example: I was charged twice for the same order.
    Decider:
      type: object
      properties:
        policy_ids:
          description: The policies every decision's backend acts under. Empty for one written without any,
            which does not run until a write gives it one.
          type: array
          items:
            x-naturali-ref: policies
            type: string
          example:
            - pol_V1StGXR8Z5jdHi6B
        id:
          type: string
          example: dcd_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        name:
          type: string
          example: support-triage
        description:
          type: string
          nullable: true
        agent_id:
          x-naturali-ref: agents
          type: string
          nullable: true
          description: The tool-less agent that answers; null when a tool does
          example: agent_V1StGXR8Z5jdHi6B
        tool_id:
          x-naturali-ref: tools
          type: string
          nullable: true
          description: The tool that answers, run with no action; null when an agent does
          example: tool_V1StGXR8Z5jdHi6B
        version:
          type: integer
          description: The question set's version. Bumped only by a write that changes `questions`.
          example: 1
        questions:
          $ref: "#/components/schemas/DeciderQuestions"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateDeciderRequest:
      type: object
      additionalProperties: false
      description: Names exactly one of `agent_id` and `tool_id`.
      required:
        - name
        - questions
        - policy_ids
      properties:
        policy_ids:
          description: The policies every decision's backend acts under.
          allOf:
            - $ref: "#/components/schemas/AttachedPolicyIds"
        name:
          type: string
          description: Human-readable name, unique per project
          example: support-triage
        description:
          type: string
          nullable: true
        agent_id:
          x-naturali-ref: agents
          type: string
          description: A tool-less agent that answers
          example: agent_V1StGXR8Z5jdHi6B
        tool_id:
          x-naturali-ref: tools
          type: string
          description: A tool that answers, run with no action
          example: tool_V1StGXR8Z5jdHi6B
        questions:
          $ref: "#/components/schemas/DeciderQuestions"
        version_label:
          type: string
          description: Optional tag for version 1, e.g. `initial`
          example: initial
    UpdateDeciderRequest:
      type: object
      additionalProperties: false
      properties:
        policy_ids:
          description: Replaces the policies every decision's backend acts under.
          allOf:
            - $ref: "#/components/schemas/AttachedPolicyIds"
        name:
          type: string
        description:
          type: string
          nullable: true
        agent_id:
          x-naturali-ref: agents
          type: string
          description: Replaces the backend with this agent
        tool_id:
          x-naturali-ref: tools
          type: string
          description: Replaces the backend with this tool
        questions:
          $ref: "#/components/schemas/DeciderQuestions"
        version_label:
          type: string
          description: Optional tag for the version this write creates. Ignored when the write changes no
            question, since no version is archived.
          example: add-account-option
        expected_version:
          description: Refuses the write unless the decider is at this version.
          allOf:
            - $ref: "#/components/schemas/ExpectedVersion"
    DeciderVersion:
      type: object
      description: An immutable archive of a decider's question set at one version.
      properties:
        id:
          type: string
          example: dcd_ver_V1StGXR8Z5jdHi6B
        decider_id:
          x-naturali-ref: deciders
          type: string
          example: dcd_V1StGXR8Z5jdHi6B
        version:
          type: integer
          example: 1
        config:
          type: object
          additionalProperties: true
          description: The versioned surface as it stood at this version.
          properties:
            questions:
              $ref: "#/components/schemas/DeciderQuestions"
        label:
          type: string
          nullable: true
          example: restored from v2
        created_by_principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: Who produced this version. Null for a write with no principal behind it.
        created_by_principal_id:
          type: string
          nullable: true
          description: "Public id of that principal: the user (`user_…`), or for API key auth the key itself
            (`key_…`), so the record names which key acted."
          example: user_V1StGXR8Z5jdHi6B
        created_at:
          type: string
          format: date-time
    RestoreDeciderVersionRequest:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          description: Optional tag for the new version. Defaults to `restored from vN`.
          example: rollback
    CreateDecisionRequest:
      type: object
      additionalProperties: false
      required:
        - input
      properties:
        input:
          $ref: "#/components/schemas/DecisionInput"
        metadata:
          description: Caller-owned annotations stored on the decision and returned on every read — typically
            the id of what was judged, since the input itself is not stored. Written once, with the
            decision. A non-object is rejected with `400 VALIDATION_FAILED` and no decision is
            written.
          example:
            ticket_id: ZD-48213
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
        wait:
          type: boolean
          default: false
          x-naturali-tool-forced: true
          description: True evaluates before answering and returns the settled decision. False — the default —
            returns the `queued` decision at once. A tool call, `builtin` or MCP, always waits.
          example: true
    CreateInlineDecisionRequest:
      type: object
      additionalProperties: false
      description: Names exactly one of `agent_id` and `tool_id`.
      required:
        - questions
        - input
      properties:
        agent_id:
          x-naturali-ref: agents
          type: string
          description: A tool-less agent that answers
          example: agent_V1StGXR8Z5jdHi6B
        tool_id:
          x-naturali-ref: tools
          type: string
          description: A tool that answers, run with no action
          example: tool_V1StGXR8Z5jdHi6B
        questions:
          $ref: "#/components/schemas/DeciderQuestions"
        input:
          $ref: "#/components/schemas/DecisionInput"
        metadata:
          description: Caller-owned annotations stored on the decision. A non-object is rejected with `400
            VALIDATION_FAILED`.
          example:
            ticket_id: ZD-48213
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
        wait:
          type: boolean
          default: false
          x-naturali-tool-forced: true
          description: True evaluates before answering and returns the settled decision. False — the default —
            returns the `queued` decision at once. A tool call, `builtin` or MCP, always waits.
          example: true
    AnswerProbability:
      type: object
      additionalProperties: false
      properties:
        value:
          description: The choice's `value`, or the level's index
          oneOf:
            - type: string
            - type: integer
          example: billing
        label:
          type: string
          description: The level's `label`; on a `score` answer only
        probability:
          type: number
          minimum: 0
          maximum: 1
          example: 0.95
    DecisionAnswer:
      type: object
      description: One question's answer, named after it. A `predicate` carries the `probability` its
        condition holds — 1 or 0 from an agent, which states no calibrated probability. A `choice`
        carries the chosen `choice`. A `score` carries the level index, or from a tool a
        probability-weighted value between levels. `probabilities` and `confidence` are present only
        when a tool backend supplied them, carried as supplied; the runtime does not vouch for their
        meaning.
      properties:
        type:
          type: string
          enum:
            - predicate
            - choice
            - score
        name:
          type: string
          example: department
        probability:
          type: number
          minimum: 0
          maximum: 1
          example: 0.92
        choice:
          type: string
          example: billing
        score:
          type: number
          example: 1.1
        probabilities:
          type: array
          items:
            $ref: "#/components/schemas/AnswerProbability"
        confidence:
          type: number
          minimum: 0
          maximum: 1
          example: 0.93
    Decision:
      type: object
      properties:
        id:
          type: string
          example: dec_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        decider_id:
          x-naturali-ref: deciders
          type: string
          nullable: true
          description: The decider asked; kept after the decider is deleted. Null for a decision sent with its
            own questions.
          example: dcd_V1StGXR8Z5jdHi6B
        decider_version:
          type: integer
          nullable: true
          description: The question-set version the decision was answered under
          example: 1
        questions:
          type: array
          nullable: true
          description: The questions a decision sent with its own was answered under. Null for a decider's
            decision, whose questions are its `decider_version`.
          items:
            $ref: "#/components/schemas/DeciderQuestion"
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
        answers:
          type: array
          nullable: true
          description: One answer per question, in question order. Null until the decision completes, then
            never rewritten.
          items:
            $ref: "#/components/schemas/DecisionAnswer"
        answers_by_name:
          type: object
          nullable: true
          description: The same answers keyed by question name, so a JSON Logic path reads one by name
            (`answers_by_name.department.choice`) rather than by position.
          additionalProperties:
            $ref: "#/components/schemas/DecisionAnswer"
        error:
          allOf:
            - $ref: "#/components/schemas/StoredError"
          nullable: true
          description: Why a `failed` decision failed.
        generation_id:
          x-naturali-ref: generations
          type: string
          nullable: true
          description: The generation that answered, once one has; null for a tool backend. Its receipt
            carries what the decision cost.
          example: gen_V1StGXR8Z5jdHi6B
        metadata:
          allOf:
            - $ref: "#/components/schemas/MetadataBag"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
    AttachedPolicyIds:
      type: array
      minItems: 1
      items:
        x-naturali-ref: policies
        type: string
      description: The policies the resource acts under; an event subscriber receives an event only when
        they allow reading its resource. The caller must hold every grant of each one it attaches
        inside the project, else `403 POLICY_GRANT_NOT_HELD`.
      example:
        - pol_V1StGXR8Z5jdHi6B
    ExpectedVersion:
      type: integer
      minimum: 1
      nullable: true
      description: >-
        The version the caller believes the resource holds. When the resource is at any other
        version the write is refused with `409 VERSION_CONFLICT` and nothing is written;
        `meta.current_version` on that response names the version in force.


        Omit it to write unconditionally. Omitting it does not make the write unordered: two writes
        that reach the server together are still serialized, and the one whose version was taken
        first is refused the same way. What the field adds is refusing a write whose author read the
        resource some time ago and has not seen what happened since.


        The `If-Match` header carries the same precondition for a client that prefers the HTTP
        spelling. Sending both with different versions is `400 VALIDATION_FAILED`.
      example: 3
    PrincipalType:
      type: string
      enum:
        - user
        - api_key
        - agent
        - automation
        - approval
        - trigger
        - system
        - eval
        - decider
        - ingestion_rule
        - memory_rule
        - playbook_version
      description: What kind of principal acted. `user` and `api_key` are authenticated callers, and the
        id is the user's (`user_…`) or the key's own (`key_…`), so a record names which key acted
        rather than its owner. `agent` is an agent writing under its own identity (`agent_…`).
        `automation` is the task engine acting on a dispatch outcome and `approval` an approval
        resolution; neither carries an id. `trigger` is a trigger firing under its own `policy_ids`
        (`trg_…`). `system` is the platform itself, with an id naming the mechanism
        (`retention_sweep`, `zero_retention`). `eval`, `decider`, `ingestion_rule`, `memory_rule`
        and `playbook_version` are that resource's work running under its own `policy_ids` when
        nobody started it, the id its own.
      example: user
    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
    StoredError:
      type: object
      description: Why a resource's work failed, in the shape of an error response's `error` without
        `hint`. Every `error` field a resource records carries it, so `code` can be read without
        first checking the type of `error`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A key from the server's ERROR_CODES registry, documented on the Error Codes page.
            `INTERNAL_ERROR`, with the message `Internal Server Error`, records an unexpected
            failure whose detail reaches the server log only.
          example: AI_PROVIDER_ERROR
        message:
          type: string
          example: "Provider returned 402: insufficient credits"
        meta:
          type: object
          additionalProperties: true
          description: The failure's own structured context, when it names any.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    DeciderId:
      name: decider_id
      in: path
      required: true
      description: The decider ID
      schema:
        type: string
        example: dcd_V1StGXR8Z5jdHi6B
    Version:
      name: version
      in: path
      required: true
      description: The archived version number
      schema:
        type: integer
        minimum: 1
    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
    IfMatchVersion:
      name: If-Match
      in: header
      required: false
      description: The version the caller believes the resource holds, as an entity tag (`3` or `"3"`).
        Equivalent to `expected_version` in the request body; `*` states no precondition beyond the
        resource existing. A mismatch is `409 VERSION_CONFLICT`.
      schema:
        type: string
      example: "3"
  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"
    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"
    VersionConflict:
      description: "The resource has moved past the version this write read (`VERSION_CONFLICT`): a stated
        `expected_version` or `If-Match` no longer matches, or a concurrent write took the version
        first. `meta.current_version` names the version in force. Nothing is written."
      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"
