# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/triggers.yaml (runtime 0.71.2)
#  + policy: openapi/mirror-policies/triggers.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Triggers API
  version: 1.0.0
  description: >-
    Triggers: what starts an automation without a caller — a schedule, an inbound webhook, or a
    manual fire — pointed at an agent, a tool, an orchestration or an eval, with every firing
    recorded. 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, #304): 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: Triggers
    description: Manage triggers and inspect firings
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/triggers:
    get:
      description: Lists triggers. Filter by project, starter type, or target type.
      tags:
        - Triggers
      summary: List triggers
      operationId: listTriggers
      parameters:
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - manual
              - webhook
              - schedule
              - event
        - name: target_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - orchestration
              - agent
              - tool
              - eval
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          description: Number of results to skip
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: A list of triggers
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                  - limit
                  - offset
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Trigger"
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
    post:
      description: Creates a new trigger for a project
      tags:
        - Triggers
      summary: Create a trigger
      operationId: createTrigger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTriggerRequest"
      responses:
        "201":
          description: Trigger created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerWithSecret"
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/triggers/{trigger_id}:
    get:
      description: Retrieves the details of a specific trigger
      tags:
        - Triggers
      summary: Get a trigger
      operationId: getTrigger
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Trigger details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Trigger"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    patch:
      description: >
        Updates an existing trigger's configuration. The type is immutable. Changing `target_type`
        or `target_id` re-checks the target-start action (`orchestrations:StartRun`,
        `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a
        firing runs with the trigger creator's authority rather than the updater's. A caller who
        could not start the new target is answered `403` and the trigger keeps the target it had.
      tags:
        - Triggers
      summary: Update a trigger
      operationId: updateTrigger
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTriggerRequest"
      responses:
        "200":
          description: Trigger updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Trigger"
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    delete:
      description: Deletes a trigger
      tags:
        - Triggers
      summary: Delete a trigger
      operationId: deleteTrigger
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Trigger deleted
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/triggers/{trigger_id}/fire:
    post:
      description: Fires a trigger synchronously and returns the terminal firing record. The firing itself
        always settles here; an `eval` target's run is queued rather than executed inline, so the
        record names a `queued` run to poll.
      tags:
        - Triggers
      summary: Fire a trigger
      operationId: fireTrigger
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FireTriggerRequest"
      responses:
        "200":
          description: Terminal firing record
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerFiring"
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
        "409":
          description: Trigger inactive or creator unavailable
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/triggers/{trigger_id}/secret:
    get:
      description: Retrieves the signing secret for a webhook trigger
      tags:
        - Triggers
      summary: Get trigger secret
      operationId: getTriggerSecret
      x-naturali-agent-exclude: true
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Trigger secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerSecretResponse"
        "400":
          description: Trigger is not a webhook trigger
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/triggers/{trigger_id}/rotate-secret:
    post:
      description: Rotates the signing secret for a webhook trigger
      tags:
        - Triggers
      summary: Rotate trigger secret
      operationId: rotateTriggerSecret
      x-naturali-agent-exclude: true
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Secret rotated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerWithSecret"
        "400":
          description: Trigger is not a webhook trigger
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/trigger-firings:
    get:
      description: Lists firings for a trigger (trigger_id is required).
      tags:
        - Triggers
      summary: List trigger firings
      operationId: listTriggerFirings
      parameters:
        - name: trigger_id
          in: query
          required: true
          description: Trigger to list firings for (trg_...)
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: A list of firings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerFiringListResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Trigger not found
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/trigger-firings/{firing_id}:
    get:
      description: Retrieves the details of a specific trigger firing
      tags:
        - Triggers
      summary: Get a trigger firing
      operationId: getTriggerFiring
      parameters:
        - name: firing_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Firing details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TriggerFiring"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Firing not found
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    Trigger:
      type: object
      properties:
        id:
          type: string
        project_id:
          x-naturali-ref: projects
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - manual
            - webhook
            - schedule
            - event
        target_type:
          type: string
          enum:
            - orchestration
            - agent
            - tool
            - eval
        target_id:
          type: string
          description: Public ID of the target resource (orchestration, agent, tool, or eval)
        action:
          type: string
          nullable: true
          description: Tool targets only — the action for mcp tools
        input:
          type: object
          nullable: true
          description: Static input, shallow-merged under fire-time input. For `eval` targets the effective
            input may carry `agent_version` and `baseline_run_id`, which are passed to the queued
            run.
        cron:
          type: string
          nullable: true
          description: 5-field cron expression (UTC). Present only for schedule triggers
        event_pattern:
          type: string
          nullable: true
          description: "Internal-event subscription pattern. Present only for event triggers: `*`, `prefix.*`,
            or an exact event name"
        active:
          type: boolean
        policy_id:
          x-naturali-ref: policies
          type: string
          nullable: true
          description: Optional boundary policy that further restricts firings
        next_fire_at:
          type: string
          format: date-time
          nullable: true
          description: Read-only, schedule triggers only. Server-computed next fire time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TriggerWithSecret:
      allOf:
        - $ref: "#/components/schemas/Trigger"
        - type: object
          properties:
            secret:
              type: string
              description: Webhook triggers only. Returned only on create and rotate
    CreateTriggerRequest:
      type: object
      required:
        - name
        - type
        - target_type
        - target_id
      additionalProperties: false
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - manual
            - webhook
            - schedule
            - event
        target_type:
          type: string
          enum:
            - orchestration
            - agent
            - tool
            - eval
        target_id:
          type: string
        action:
          type: string
          description: Tool targets only — the action for mcp tools
        input:
          type: object
        tool_context:
          type: object
          additionalProperties:
            type: string
          description: >
            Caller context every firing forwards to the run it starts, so an agent whose tools
            authorize through `{{context:<key>}}` can be put on a schedule — a firing has no request
            to carry one. Each key is forwarded as one `X-Naturali-Context-<key>` header.


            **Write-only.** It is accepted here and never returned on a read, so the record cannot
            be used to recover a value.


            A value may be a `{{secret:sec_...}}` reference, which keeps the credential in the
            [secret](/docs/modules/secrets) store and leaves only its id on the trigger; it is
            resolved at fire time, so rotating the secret changes the next firing without touching
            the trigger. A reference is refused here rather than at fire time when it is not in that
            id form (a secret's name does not resolve) or names a secret that does not exist in this
            project.
        cron:
          type: string
          description: 5-field cron expression (UTC). Required when type is schedule
        event_pattern:
          type: string
          description: Internal-event subscription pattern. Required when type is event, rejected otherwise.
            `*` matches every event, `prefix.*` a namespace, or give an exact event name such as
            `documents.ingested`
        active:
          type: boolean
          default: true
        policy_id:
          x-naturali-ref: policies
          type: string
    UpdateTriggerRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        target_type:
          type: string
          enum:
            - orchestration
            - agent
            - tool
            - eval
        target_id:
          type: string
        action:
          type: string
          nullable: true
        input:
          type: object
          nullable: true
        tool_context:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >
            Replaces the stored bag; `null` clears it. Write-only and resolved at fire time — see
            `CreateTriggerRequest.tool_context`.
        cron:
          type: string
          nullable: true
        event_pattern:
          type: string
          nullable: true
        active:
          type: boolean
        policy_id:
          x-naturali-ref: policies
          type: string
          nullable: true
    FireTriggerRequest:
      type: object
      additionalProperties: false
      properties:
        input:
          type: object
          description: Fire-time input, shallow-merged over the trigger's static input. For `eval` targets it
            may carry `agent_version` and `baseline_run_id`.
        tool_context:
          type: object
          additionalProperties:
            type: string
          description: >
            Fire-time caller context, shallow-merged per key over the trigger's stored
            `tool_context`. A manual fire has a caller, so this is the one path that can supply a
            value without storing it.


            Forwarded exactly as written: a `{{secret:...}}` reference is resolved only in the
            trigger's stored bag, never in one supplied here.
    TriggerSecretResponse:
      type: object
      properties:
        secret:
          type: string
    TriggerFiring:
      type: object
      properties:
        id:
          type: string
        trigger_id:
          x-naturali-ref: triggers
          type: string
        project_id:
          x-naturali-ref: projects
          type: string
        source:
          type: string
          enum:
            - manual
            - webhook
            - schedule
            - event
        status:
          type: string
          enum:
            - pending
            - running
            - succeeded
            - failed
        input:
          type: object
          nullable: true
        result:
          type: object
          nullable: true
          description: "{ target_type, result_id, status, output } — output truncated"
        error:
          type: object
          nullable: true
          description: "{ code, message, meta }"
        idempotency_key:
          type: string
          nullable: true
          description: "`<event_id>:<trigger_id>` for an `event` firing, null for every other source. The same
            event reaching the same trigger twice produces one firing under this key, so a consumer
            reading firings can recognise a redelivery."
        attempts:
          type: integer
          description: Dispatch attempts started. Above 1 means an earlier attempt was interrupted before it
            recorded a result and the firing was redelivered — not that the target refused it, which
            is recorded terminally in `error` and never retried.
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TriggerFiringListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/TriggerFiring"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
  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.