# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/workflows.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/workflows.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Workflows API
  version: 1.0.0
  description: >-
    Workflows: the state machines tasks move through — states, the transitions between them, their
    guards and the automation each one fires — versioned so a change never rewrites the history of
    work already done. 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: Workflows
    description: Manage workflow definitions
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/workflows:
    get:
      description: Lists workflow definitions in a project.
      tags:
        - Workflows
      summary: List workflows
      operationId: listWorkflows
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A list of workflows
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Workflow"
        "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:
      description: Creates a new workflow definition. The definition is statically validated.
      tags:
        - Workflows
      summary: Create a workflow
      operationId: createWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkflowRequest"
      responses:
        "201":
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        "400":
          description: Bad request (invalid definition)
          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 workflow with this name already exists
          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}/workflows/{workflow_id}:
    get:
      description: Retrieves a workflow definition.
      tags:
        - Workflows
      summary: Get a workflow
      operationId: getWorkflow
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        "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: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      description: Updates a workflow definition. Structural changes (states/transitions) are
        re-validated. Existing tasks in a removed state stay put but can only leave via transitions
        valid in the new definition.
      tags:
        - Workflows
      summary: Update a workflow
      operationId: updateWorkflow
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IfMatchVersion"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkflowRequest"
      responses:
        "200":
          description: Workflow updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        "400":
          description: Bad request (invalid definition)
          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: Workflow 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:
      description: Deletes a workflow. Rejected while open tasks exist.
      tags:
        - Workflows
      summary: Delete a workflow
      operationId: deleteWorkflow
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Workflow 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: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The workflow has open tasks and cannot be deleted
          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}/workflows/{workflow_id}/versions:
    get:
      description: >
        Returns the workflow's archived state machines, newest first. A version is written on create
        and on every subsequent write that changes the definition (`states`, `transitions`,
        `payload_schema`) — through the REST API or a formation apply alike. Metadata-only edits
        (name, description) do not archive a version. See
        [Versioning](/docs/modules/workflows#versioning).
      tags:
        - Workflows
      summary: List a workflow's versions
      operationId: listWorkflowVersions
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of workflow versions, newest first
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/WorkflowVersion"
        "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: Workflow 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}/workflows/{workflow_id}/versions/{version}:
    get:
      description: >
        Returns the exact state machine a given version describes. Every task records the version it
        runs on in `workflow_version`, fixed at creation and moved only by migrate-task, so this is
        how you read the definition a task is actually being validated against — including a task
        whose workflow has been rewired since.
      tags:
        - Workflows
      summary: Fetch an archived workflow version
      operationId: getWorkflowVersion
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The archived version number
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Archived workflow version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowVersion"
        "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"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/workflows/{workflow_id}/versions/{version}/restore:
    post:
      description: >
        Writes an archived version's state machine back as the workflow's live definition, which
        archives it again as a **new** version rather than rewinding the counter — so a task pinned
        to any version in between still runs on the machine it entered on.


        The restore runs through the ordinary update path, so the archived definition goes through
        the same validation as an authored one. That includes resolving every `on_enter` dispatch
        target, so restoring a version whose agent or orchestration has since been deleted fails
        with `400` rather than writing a definition that would strand a task on entry. Restoring the
        definition the workflow already holds is a no-op and archives nothing. Tasks already in
        flight are unaffected either way — a restore is an ordinary edit, and pinning is what keeps
        it from reaching them.
      tags:
        - Workflows
      summary: Restore an archived workflow state machine
      operationId: restoreWorkflowVersion
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The archived version number
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestoreWorkflowVersionRequest"
      responses:
        "200":
          description: The workflow, at its new version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        "400":
          description: Bad request — version is not a positive integer, or the restored definition is invalid
          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}/workflows/{workflow_id}/migrations:
    post:
      description: "Moves every open task of the workflow that runs on an older version, or on none, onto
        `to_version`. Each task is migrated as migrate-task migrates one and needs
        `tasks:MigrateTask` on it; a task it would refuse is reported as `refused` with the error,
        and the run goes on. The tasks and the caller's permission on each are fixed when the run is
        recorded. A `state_map` target the version lacks, or a terminal one, refuses the request
        before any task moves. Runs in the background by default (`status: queued`); `wait: true`
        answers once every task has settled. See [Migrating every open
        task](/docs/modules/workflows#migrating-every-open-task)."
      tags:
        - Workflows
      summary: Migrate a workflow's open tasks to one of its versions
      operationId: createWorkflowMigration
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The workflow whose tasks migrate.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkflowMigrationRequest"
      responses:
        "201":
          description: "The run, `queued` in the background or `completed` with `wait: true`"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowMigration"
        "400":
          description: The version does not exist, or a `state_map` target is undeclared or terminal
          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: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/workflows/{workflow_id}/migrations/{migration_id}:
    get:
      description: Returns a workflow migration with the outcome of each task.
      tags:
        - Workflows
      summary: Get a workflow migration
      operationId: getWorkflowMigration
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The workflow whose tasks migrate.
          schema:
            type: string
        - name: migration_id
          in: path
          required: true
          description: The workflow migration to read.
          schema:
            type: string
            example: wfl_mig_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: The workflow migration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowMigration"
        "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: Workflow or migration 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:
    WorkflowState:
      type: object
      description: "A named state. Exactly one state must be `initial: true`; any number may be `terminal:
        true`. A `kind: human` state never dispatches — the task parks until a transition fires.
        `on_enter` (§5) dispatches exactly one of an agent generation (`kind: agent`, `agent_id`),
        an orchestration run (`kind: orchestration`, `orchestration_id`) or a tool call (`kind:
        tool`, `tool_id`, optional `operation_id`) on entry, optionally under a `retry` policy
        (`max_attempts` 1-10, `backoff_seconds`, `backoff_multiplier`) that re-runs execution
        failures before `on_failure` applies. A `tool` dispatch settles within the dispatch and is
        adjudicated by the same guardrails as an orchestration `tool` node; for anything that must
        wait (a delay, a poll, a multi-step pipeline, or an approval-gated tool), dispatch an
        orchestration instead."
      required:
        - name
      properties:
        name:
          type: string
        initial:
          type: boolean
        terminal:
          type: boolean
        kind:
          type: string
          description: "`human` marks a human-in-the-loop parking state: the state never dispatches (declaring
            `on_enter` on it is rejected at validation) and the task parks until a principal fires a
            transition."
        stalled_after:
          type: integer
          nullable: true
          description: Seconds a task may sit in this state before the stall sweeper emits a `tasks.stalled`
            event (once per stall episode, re-armed on the next transition). Must be a positive
            integer when set. Omit or null to never stall. The event does not move the task — route
            on it with a webhook/trigger.
        on_enter:
          type: object
          nullable: true
          description: What entering the state dispatches, and how the result routes. Omitted or null on a
            state that only parks.
          properties:
            dispatch:
              type: object
              description: "The one thing entering the state runs. `kind` picks it and names the id it needs:
                `agent` → `agent_id`, `orchestration` → `orchestration_id`, `tool` → `tool_id` (with
                an optional `operation_id`)."
              properties:
                kind:
                  type: string
                  enum:
                    - agent
                    - orchestration
                    - tool
                  description: Which target is dispatched.
                agent_id:
                  x-naturali-ref: agents
                  type: string
                  nullable: true
                  description: "The agent a `kind: agent` dispatch generates with."
                orchestration_id:
                  x-naturali-ref: orchestrations
                  type: string
                  nullable: true
                  description: "The orchestration a `kind: orchestration` dispatch starts a run of."
                tool_id:
                  x-naturali-ref: tools
                  type: string
                  nullable: true
                  description: "The tool a `kind: tool` dispatch calls."
                operation_id:
                  type: string
                  nullable: true
                  description: Which operation of a multi-operation tool to invoke — the same selector an
                    orchestration `tool` node takes.
                input_mapping:
                  type: object
                  nullable: true
                  additionalProperties: true
                  description: JSON Logic building the dispatch input from the task. Carried verbatim.
                payload_writes:
                  type: object
                  nullable: true
                  additionalProperties: true
                  description: JSON Logic expressions over `{task, result}` whose values are written into
                    `task.payload` when the dispatch completes, one named channel per key. Carried
                    verbatim.
            retry:
              type: object
              nullable: true
              description: Re-runs the dispatch's execution failures before `on_failure` applies. Omitted means a
                single attempt.
              properties:
                max_attempts:
                  type: integer
                  description: Attempts to make, 1–10.
                backoff_seconds:
                  type: number
                  nullable: true
                  description: Delay before the second attempt.
                backoff_multiplier:
                  type: number
                  nullable: true
                  description: "Factor the delay grows by per further attempt: `backoff_seconds *
                    backoff_multiplier^(n - 2)`."
            on_complete:
              type: array
              nullable: true
              description: Rules evaluated in order when the dispatch completes; the first whose `when` is truthy
                fires its transition.
              items:
                type: object
                properties:
                  when:
                    description: JSON Logic over `{task, result}`. Carried verbatim.
                  transition:
                    type: string
                    description: The transition to fire, by name.
            on_failure:
              type: string
              nullable: true
              description: "Transition fired when the dispatch fails after its last attempt. Omitted parks the
                task with `automation_status: failed`."
    WorkflowTransition:
      type: object
      description: A named, directional move. `from` is a list of source states; `to` is one target state.
        `guard` is a JSON Logic expression over `{task, transition, principal}` that must be truthy
        for the move to apply.
      required:
        - name
        - from
        - to
      properties:
        name:
          type: string
        from:
          type: array
          items:
            type: string
        to:
          type: string
        guard:
          type: object
          nullable: true
        requires_approval:
          type: boolean
          description: Gate the transition behind a human approval. When `true`, firing the transition (by
            anyone other than the approval resolution itself) parks a pending `ApprovalItem` instead
            of moving the task; the task exposes `pending_transition` until the item resolves.
            Approval fires the transition as the `approval` principal (its guard re-evaluated at
            resolution time); rejection or expiry clears the gate and appends a history note.
    Workflow:
      type: object
      properties:
        id:
          type: string
        project_id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        version:
          type: integer
          description: >
            Incremented on every write that changes the state machine; prior versions are archived.
            A task pins the version it entered on, so these fields are a draft for tasks created
            from now on rather than a live rewrite of the ones already in flight.
          example: 1
        states:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowState"
        transitions:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowTransition"
        payload_schema:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateWorkflowRequest:
      type: object
      required:
        - name
        - states
        - transitions
      additionalProperties: false
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        states:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowState"
        transitions:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowTransition"
        payload_schema:
          type: object
          nullable: true
        version_label:
          type: string
          description: Optional tag for the version this create archives, e.g. `initial`.
          example: initial
    UpdateWorkflowRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        states:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowState"
        transitions:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowTransition"
        payload_schema:
          type: object
          nullable: true
        version_label:
          type: string
          description: Optional tag for the version this write creates, e.g. `rewired`. Ignored when the write
            changes no definition field, since no version is archived.
          example: rewired
        expected_version:
          description: Refuses the write unless the resource is at this version.
          allOf:
            - $ref: "#/components/schemas/ExpectedVersion"
    WorkflowVersion:
      type: object
      description: An immutable archive of a workflow's state machine at one version.
      properties:
        id:
          type: string
          description: Public ID of the archived version
          example: wfl_ver_V1StGXR8Z5jdHi6B
        workflow_id:
          x-naturali-ref: workflows
          type: string
          description: Public ID of the workflow this version belongs to
          example: wfl_V1StGXR8Z5jdHi6B
        version:
          type: integer
          description: The archived version number
          example: 1
        config:
          type: object
          additionalProperties: true
          description: >-
            The workflow's versioned surface as it stood at this version: `states`, `transitions`
            and `payload_schema`. Name and description are metadata — bumping the version when one
            of them changes would make two version numbers denote the same state machine, which is
            exactly what a task cites.


            Deliberately open rather than a fixed schema: an archive written by an earlier release
            of the runtime reflects the workflow surface **of its own time**, so it may carry fields
            the current API no longer documents.
          properties:
            states:
              type: array
              items:
                $ref: "#/components/schemas/WorkflowState"
            transitions:
              type: array
              items:
                $ref: "#/components/schemas/WorkflowTransition"
            payload_schema:
              type: object
              nullable: true
        label:
          type: string
          nullable: true
          description: Optional human tag for this version, e.g. `rewired`. Set from the `version_label` field
            of a write, the `label` field of a restore, or generated for one.
          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
    CreateWorkflowMigrationRequest:
      type: object
      required:
        - to_version
      additionalProperties: false
      properties:
        to_version:
          type: integer
          minimum: 1
          description: The workflow version to move the open tasks onto.
        state_map:
          type: object
          additionalProperties:
            type: string
          description: Current state name to a state the target version declares, applied to every task as
            migrate-task applies it to one.
        wait:
          type: boolean
          default: false
          description: When omitted or `false` (default), the run is answered `queued` and settles in the
            background; poll get-workflow-migration. Pass `true` to answer once every task has
            settled.
    WorkflowMigrationTask:
      type: object
      required:
        - task_id
        - status
        - error
      properties:
        task_id:
          type: string
          example: task_V1StGXR8Z5jdHi6B
        status:
          type: string
          enum:
            - pending
            - migrated
            - refused
        error:
          allOf:
            - $ref: "#/components/schemas/StoredError"
          nullable: true
          description: "Why the task was refused: `{ code, message, meta? }`; null otherwise"
    WorkflowMigration:
      type: object
      required:
        - id
        - workflow_id
        - project_id
        - to_version
        - state_map
        - status
        - task_count
        - migrated_count
        - refused_count
        - tasks
        - created_by_principal_type
        - created_by_principal_id
        - created_at
        - finished_at
      properties:
        id:
          type: string
          example: wfl_mig_V1StGXR8Z5jdHi6B
        workflow_id:
          type: string
          example: wfl_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        to_version:
          type: integer
        state_map:
          type: object
          nullable: true
          additionalProperties:
            type: string
        status:
          type: string
          enum:
            - queued
            - running
            - completed
          description: "`completed` once every task is `migrated` or `refused`."
        task_count:
          type: integer
        migrated_count:
          type: integer
        refused_count:
          type: integer
        tasks:
          type: array
          description: Every task the run covers, in the order it migrates them.
          items:
            $ref: "#/components/schemas/WorkflowMigrationTask"
        created_by_principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: Who started the migration.
        created_by_principal_id:
          type: string
          nullable: true
          description: Public id of who started the migration.
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: When the last task settled; null until then.
    RestoreWorkflowVersionRequest:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          description: Optional tag for the new version the restore archives. Defaults to `restored from vN`.
          example: rollback to pre-rewire
    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`.
    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
    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
    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"
    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"
