trigger-dev-management-openapi.yml

openapi: 3.0.3
info:
  title: Trigger.dev Management API
  description: >-
    The Trigger.dev Management API provides comprehensive REST endpoints for managing
    workflow runs, tasks, schedules, deployments, queues, environment variables,
    batches, and waitpoints. Enables programmatic control over the full lifecycle
    of background job workflows including triggering, monitoring, cancellation,
    and observability. Authenticated via bearer token (secret API key starting
    with tr_dev_, tr_prod_, or tr_stg_).
  version: 3.1.0
  contact:
    url: https://trigger.dev
  license:
    name: AGPL-3.0
    url: https://github.com/triggerdotdev/trigger.dev/blob/main/LICENSE
servers:
  - url: https://api.trigger.dev
    description: Trigger.dev Cloud API
  - url: https://your-self-hosted-instance.com
    description: Self-hosted Trigger.dev instance
security:
  - bearerAuth: []
tags:
  - name: Tasks
    description: Trigger individual or batched task runs.
  - name: Runs
    description: List, retrieve, cancel, replay, reschedule, tag, and inspect run events, results, and traces.
  - name: Schedules
    description: Create and manage cron schedules with IANA timezone support.
  - name: Deployments
    description: List deployments and promote versions to production.
  - name: Queues
    description: Manage task queues including pause, resume, and concurrency overrides.
  - name: Environment Variables
    description: Create, read, update, delete, and import environment variables per project and environment.
  - name: Batches
    description: Create and retrieve large-scale batch runs.
  - name: Waitpoints
    description: Create, list, retrieve, and complete waitpoint tokens for human-in-the-loop workflows.
  - name: Query
    description: Execute TRQL queries against runs, tasks, and metrics for dashboards and analytics.
paths:

  # ── Tasks ──────────────────────────────────────────────────────────
  /api/v1/tasks/{taskIdentifier}/trigger:
    post:
      operationId: triggerTask
      summary: Trigger Task
      description: >-
        Trigger a single task run. Returns the run ID for tracking.
        Supports payload, context, queue options, concurrency keys, idempotency,
        TTL, delay, tags, and machine preset selection.
      tags:
        - Tasks
      parameters:
        - name: taskIdentifier
          in: path
          required: true
          schema:
            type: string
          description: The task identifier (e.g., my-task)
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerTaskRequest'
      responses:
        '200':
          description: Task triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerTaskResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Task not found

  /api/v1/tasks/batch:
    post:
      operationId: batchTriggerTask
      summary: Batch Trigger Tasks
      description: >-
        Trigger multiple task runs in a single batch request. Returns a batch ID
        and array of run IDs. All items in the batch must reference the same task.
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchTriggerRequest'
      responses:
        '200':
          description: Batch triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchTriggerResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized

  # ── Runs ───────────────────────────────────────────────────────────
  /api/v1/runs:
    get:
      operationId: listRuns
      summary: List Runs
      description: >-
        Returns a paginated list of runs filtered by status, task, tags,
        date range, and other criteria.
      tags:
        - Runs
      parameters:
        - name: filter[status]
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RunStatus'
          description: Filter by run status
        - name: filter[taskIdentifier]
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by task identifiers
        - name: filter[tag]
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by tags
        - name: filter[isTest]
          in: query
          schema:
            type: boolean
          description: Filter to test runs only
        - name: filter[createdAt.from]
          in: query
          schema:
            type: string
            format: date-time
          description: Filter runs created after this time
        - name: filter[createdAt.to]
          in: query
          schema:
            type: string
            format: date-time
          description: Filter runs created before this time
        - name: page[size]
          in: query
          schema:
            type: integer
            minimum: 10
            maximum: 100
            default: 25
          description: Runs per page
        - name: page[after]
          in: query
          schema:
            type: string
          description: Run ID to paginate after
        - name: page[before]
          in: query
          schema:
            type: string
          description: Run ID to paginate before
      responses:
        '200':
          description: Paginated list of runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunsResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized

  /api/v1/runs/{runId}:
    get:
      operationId: getRunById
      summary: Retrieve Run
      description: >-
        Retrieve detailed information about a specific run including status,
        payload, output, hierarchy (root/parent/children), attempts, tags,
        and cost metadata.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Run identifier (prefixed with run_)
      responses:
        '200':
          description: Run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '401':
          description: Unauthorized
        '404':
          description: Run not found

  /api/v1/runs/{runId}/cancel:
    post:
      operationId: cancelRun
      summary: Cancel Run
      description: Cancel a queued or executing run.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Run identifier
      responses:
        '200':
          description: Run cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '404':
          description: Run not found

  /api/v1/runs/{runId}/replay:
    post:
      operationId: replayRun
      summary: Replay Run
      description: >-
        Replay a completed run with the same payload. Creates a new run
        with the original task and payload.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Run identifier
      responses:
        '200':
          description: New run created via replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerTaskResponse'
        '404':
          description: Run not found

  /api/v1/runs/{runId}/reschedule:
    post:
      operationId: rescheduleRun
      summary: Reschedule Run
      description: Reschedule a delayed run to execute at a new time.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [delay]
              properties:
                delay:
                  type: string
                  description: New delay duration (e.g., 1h, 30m)
      responses:
        '200':
          description: Run rescheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'

  /api/v1/runs/{runId}/tags:
    put:
      operationId: addTagsToRun
      summary: Add Tags to Run
      description: Add one or more tags to an existing run for filtering and organization.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tags]
              properties:
                tags:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    maxLength: 128
      responses:
        '200':
          description: Tags added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'

  /api/v1/runs/{runId}/events:
    get:
      operationId: retrieveRunEvents
      summary: Retrieve Run Events
      description: Retrieve the OpenTelemetry spans / events for a specific run, including timing, level, kind, and nested events. Used for tracing and debugging task execution.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Run identifier (prefixed with run_)
      responses:
        '200':
          description: List of run events
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunEvent'
        '401':
          description: Unauthorized
        '404':
          description: Run not found

  /api/v1/runs/{runId}/result:
    get:
      operationId: retrieveRunResult
      summary: Retrieve Run Result
      description: Retrieve the final result of a completed run, including output payload or error details.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Run result
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  output:
                    description: Successful output payload
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                      stack:
                        type: string
        '404':
          description: Run not found

  /api/v1/runs/{runId}/trace:
    get:
      operationId: retrieveRunTrace
      summary: Retrieve Run Trace
      description: Retrieve the distributed trace tree for a run including all child runs, spans, and timing data.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Run trace tree
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Run not found

  /api/v1/runs/{runId}/metadata:
    put:
      operationId: updateRunMetadata
      summary: Update Run Metadata
      description: Update the metadata object attached to a run. Useful for storing custom progress or context.
      tags:
        - Runs
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Metadata updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'

  # ── Schedules ─────────────────────────────────────────────────────
  /api/v1/schedules:
    get:
      operationId: listSchedules
      summary: List Schedules
      description: Returns all configured schedules for the project.
      tags:
        - Schedules
      responses:
        '200':
          description: List of schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
    post:
      operationId: createSchedule
      summary: Create Schedule
      description: >-
        Create a new cron schedule that triggers a task on a recurring basis.
        Supports IANA timezone configuration and deduplication keys.
      tags:
        - Schedules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleRequest'
      responses:
        '200':
          description: Schedule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '400':
          description: Bad request

  /api/v1/schedules/{scheduleId}:
    get:
      operationId: getScheduleById
      summary: Retrieve Schedule
      description: Get details of a specific schedule including next run time and status.
      tags:
        - Schedules
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
          description: Schedule identifier (prefixed with sched_)
      responses:
        '200':
          description: Schedule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
    put:
      operationId: updateSchedule
      summary: Update Schedule
      description: Update an existing schedule's cron expression, timezone, or external ID.
      tags:
        - Schedules
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
      responses:
        '200':
          description: Schedule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
    delete:
      operationId: deleteSchedule
      summary: Delete Schedule
      description: Permanently delete a schedule.
      tags:
        - Schedules
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule deleted

  /api/v1/schedules/{scheduleId}/activate:
    post:
      operationId: activateSchedule
      summary: Activate Schedule
      description: Activate a deactivated schedule to resume its execution.
      tags:
        - Schedules
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule activated

  /api/v1/schedules/{scheduleId}/deactivate:
    post:
      operationId: deactivateSchedule
      summary: Deactivate Schedule
      description: Pause a schedule without deleting it.
      tags:
        - Schedules
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule deactivated

  /api/v1/schedules/timezones:
    get:
      operationId: getTimezones
      summary: Get Timezones
      description: Returns a list of valid IANA timezone identifiers for schedule configuration.
      tags:
        - Schedules
      responses:
        '200':
          description: List of IANA timezone identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  # ── Deployments ───────────────────────────────────────────────────
  /api/v1/deployments:
    get:
      operationId: listDeployments
      summary: List Deployments
      description: Returns all deployments for the project, including version and status.
      tags:
        - Deployments
      responses:
        '200':
          description: List of deployments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Deployment'

  /api/v1/deployments/{deploymentId}:
    get:
      operationId: getDeploymentById
      summary: Get Deployment
      description: Retrieve details of a specific deployment.
      tags:
        - Deployments
      parameters:
        - name: deploymentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deployment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'

  /api/v1/deployments/latest:
    get:
      operationId: getLatestDeployment
      summary: Get Latest Deployment
      description: Returns the most recent deployment for the project.
      tags:
        - Deployments
      responses:
        '200':
          description: Latest deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'

  /api/v1/deployments/{deploymentId}/promote:
    post:
      operationId: promoteDeployment
      summary: Promote Deployment
      description: Promote a specific deployment version to production.
      tags:
        - Deployments
      parameters:
        - name: deploymentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deployment promoted

  # ── Queues ────────────────────────────────────────────────────────
  /api/v1/queues:
    get:
      operationId: listQueues
      summary: List Queues
      description: Returns all task queues for the project.
      tags:
        - Queues
      responses:
        '200':
          description: List of queues
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Queue'

  /api/v1/queues/{queueName}:
    get:
      operationId: getQueueByName
      summary: Retrieve Queue
      description: Get details of a specific queue including current depth and concurrency settings.
      tags:
        - Queues
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
          description: Queue name
      responses:
        '200':
          description: Queue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'

  /api/v1/queues/{queueName}/pause:
    post:
      operationId: pauseQueue
      summary: Pause Queue
      description: Pause a queue to prevent new runs from starting.
      tags:
        - Queues
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Queue paused

  /api/v1/queues/{queueName}/resume:
    post:
      operationId: resumeQueue
      summary: Resume Queue
      description: Resume a paused queue to allow runs to execute.
      tags:
        - Queues
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Queue resumed

  /api/v1/queues/{queueName}/concurrency:
    put:
      operationId: overrideQueueConcurrency
      summary: Override Queue Concurrency
      description: Override the concurrency limit for a queue.
      tags:
        - Queues
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                concurrencyLimit:
                  type: integer
                  description: New concurrency limit
      responses:
        '200':
          description: Concurrency limit updated

  /api/v1/queues/{queueName}/concurrency/reset:
    post:
      operationId: resetQueueConcurrency
      summary: Reset Queue Concurrency
      description: Reset a queue's concurrency limit to its default.
      tags:
        - Queues
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Concurrency limit reset

  # ── Environment Variables ─────────────────────────────────────────
  /api/v1/envvars:
    get:
      operationId: listEnvVars
      summary: List Environment Variables
      description: Returns all environment variables for the project/environment.
      tags:
        - Environment Variables
      responses:
        '200':
          description: List of environment variables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnvVar'
    post:
      operationId: createEnvVar
      summary: Create Environment Variable
      description: Create a new environment variable.
      tags:
        - Environment Variables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvVarRequest'
      responses:
        '200':
          description: Environment variable created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVar'

  /api/v1/envvars/import:
    post:
      operationId: importEnvVars
      summary: Import Environment Variables
      description: Import multiple environment variables at once.
      tags:
        - Environment Variables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: Environment variables imported

  /api/v1/envvars/{name}:
    get:
      operationId: getEnvVarByName
      summary: Retrieve Environment Variable
      description: Get the value of a specific environment variable.
      tags:
        - Environment Variables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Variable name
      responses:
        '200':
          description: Environment variable details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVar'
    put:
      operationId: updateEnvVar
      summary: Update Environment Variable
      description: Update the value of an environment variable.
      tags:
        - Environment Variables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [value]
              properties:
                value:
                  type: string
      responses:
        '200':
          description: Environment variable updated
    delete:
      operationId: deleteEnvVar
      summary: Delete Environment Variable
      description: Delete an environment variable from the project.
      tags:
        - Environment Variables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Environment variable deleted

  # ── Batches ───────────────────────────────────────────────────────
  /api/v1/batches:
    post:
      operationId: createBatch
      summary: Create Batch
      description: >-
        Create a new batch of task runs. Used for large-scale parallel processing
        where runs can be streamed in incrementally.
      tags:
        - Batches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchTriggerRequest'
      responses:
        '200':
          description: Batch created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchTriggerResponse'

  /api/v1/batches/{batchId}:
    get:
      operationId: getBatchById
      summary: Retrieve Batch
      description: Get details of a specific batch including status and run count.
      tags:
        - Batches
      parameters:
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: Batch identifier
      responses:
        '200':
          description: Batch details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'

  # ── Waitpoints ────────────────────────────────────────────────────
  /api/v1/waitpoints:
    post:
      operationId: createWaitpointToken
      summary: Create Waitpoint Token
      description: >-
        Create a waitpoint token for human-in-the-loop workflows. The run
        will pause until this token is completed.
      tags:
        - Waitpoints
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotencyKey:
                  type: string
                  description: Prevent duplicate token creation
                ttl:
                  type: string
                  description: Token expiry time (e.g., 24h, 7d)
      responses:
        '200':
          description: Waitpoint token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitpointToken'

  /api/v1/waitpoints/{tokenId}:
    get:
      operationId: getWaitpointToken
      summary: Retrieve Waitpoint Token
      description: Get the status and details of a waitpoint token.
      tags:
        - Waitpoints
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Waitpoint token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitpointToken'

  /api/v1/waitpoints/{tokenId}/complete:
    post:
      operationId: completeWaitpointToken
      summary: Complete Waitpoint Token
      description: >-
        Complete a waitpoint token to resume the paused run. Optionally
        pass a result payload back to the waiting run.
      tags:
        - Waitpoints
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  description: Result data to return to the waiting run
      responses:
        '200':
          description: Waitpoint completed

  /api/v1/waitpoints/tokens:
    get:
      operationId: listWaitpointTokens
      summary: List Waitpoint Tokens
      description: Returns a paginated list of waitpoint tokens filterable by status, tags, idempotency key, and creation period.
      tags:
        - Waitpoints
      parameters:
        - name: page[size]
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Tokens per page
        - name: page[after]
          in: query
          schema:
            type: string
          description: Cursor for next page
        - name: page[before]
          in: query
          schema:
            type: string
          description: Cursor for previous page
        - name: filter[status]
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [WAITING, COMPLETED, TIMED_OUT]
        - name: filter[tags]
          in: query
          schema:
            type: array
            items:
              type: string
        - name: filter[idempotencyKey]
          in: query
          schema:
            type: string
        - name: filter[createdAt][period]
          in: query
          schema:
            type: string
            description: Time shorthand such as 24h or 7d
      responses:
        '200':
          description: Paginated list of waitpoint tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WaitpointToken'
                  pagination:
                    type: object
                    properties:
                      next:
                        type: string
                      previous:
                        type: string

  /api/v1/waitpoints/{tokenId}/callback:
    post:
      operationId: completeWaitpointTokenCallback
      summary: Complete Waitpoint Token via Callback
      description: Complete a waitpoint token by callback URL — used when an external system signals completion of a human-in-the-loop step.
      tags:
        - Waitpoints
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  description: Result payload returned to the waiting run
      responses:
        '200':
          description: Waitpoint completed via callback

  # ── Query / Dashboards ────────────────────────────────────────────
  /api/v1/query:
    post:
      operationId: executeQuery
      summary: Execute Query
      description: Execute a TRQL query against runs, tasks, and metrics. Supports environment, project, or organization scope. Returns JSON rows or CSV.
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: TRQL query string
                scope:
                  type: string
                  enum: [environment, project, organization]
                  default: environment
                period:
                  type: string
                  description: Time shorthand such as 7d or 30d
                from:
                  type: string
                  format: date-time
                to:
                  type: string
                  format: date-time
                format:
                  type: string
                  enum: [json, csv]
                  default: json
      responses:
        '200':
          description: Query result
          content:
            application/json:
              schema:
                type: object
                properties:
                  format:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid query

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Secret API key (starts with tr_dev_, tr_prod_, or tr_stg_).
        Set TRIGGER_SECRET_KEY environment variable or pass in Authorization header.

  schemas:
    RunStatus:
      type: string
      enum:
        - QUEUED
        - EXECUTING
        - REATTEMPTING
        - WAITING_FOR_DEPLOY
        - WAITING_TO_RESUME
        - COMPLETED_SUCCESSFULLY
        - COMPLETED_WITH_ERRORS
        - INTERRUPTED
        - CANCELLED
        - CRASHED
        - FAILED_TO_RUN
        - TIMED_OUT
        - EXPIRED
        - DELAYED
        - SYSTEM_FAILURE
      description: Current status of a task run

    TriggerTaskRequest:
      type: object
      properties:
        payload:
          description: Task payload data (any JSON value)
        context:
          description: Additional context data
        options:
          type: object
          properties:
            queue:
              type: object
              properties:
                name:
                  type: string
                concurrencyLimit:
                  type: integer
            concurrencyKey:
              type: string
              description: Scope concurrency to a specific key
            idempotencyKey:
              type: string
              description: Prevent duplicate runs
            ttl:
              type: string
              description: Time-to-live (e.g., 1h42m)
            delay:
              type: string
              description: Execution delay (e.g., 1h, 30d)
            tags:
              type: array
              maxItems: 10
              items:
                type: string
                maxLength: 128
            machine:
              type: string
              enum: [micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, large-2x]
              description: Machine preset for the run

    TriggerTaskResponse:
      type: object
      required: [id]
      properties:
        id:
          type: string
          description: Run identifier (prefixed with run_)

    BatchTriggerRequest:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TriggerTaskRequest'

    BatchTriggerResponse:
      type: object
      properties:
        id:
          type: string
          description: Batch identifier
        runs:
          type: array
          items:
            $ref: '#/components/schemas/TriggerTaskResponse'

    Batch:
      type: object
      properties:
        id:
          type: string
          description: Batch identifier
        status:
          type: string
          enum: [PENDING, PROCESSING, COMPLETED, FAILED]
        totalCount:
          type: integer
        completedCount:
          type: integer
        failedCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    Run:
      type: object
      required: [id, status, taskIdentifier]
      properties:
        id:
          type: string
          description: Run identifier (prefixed with run_)
        status:
          $ref: '#/components/schemas/RunStatus'
        taskIdentifier:
          type: string
          description: The task that this run executes
        version:
          type: string
          description: Deployment version that ran the task
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        isTest:
          type: boolean
        payload:
          description: The payload data passed to the task
        output:
          description: The task's return value (if completed successfully)
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        relatedRuns:
          type: object
          properties:
            root:
              $ref: '#/components/schemas/RunReference'
            parent:
              $ref: '#/components/schemas/RunReference'
            children:
              type: array
              items:
                $ref: '#/components/schemas/RunReference'
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/RunAttempt'
        schedule:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            expression:
              type: string

    RunReference:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/RunStatus'
        taskIdentifier:
          type: string

    RunAttempt:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        error:
          type: object
          properties:
            message:
              type: string
            stack:
              type: string

    ListRunsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        pagination:
          type: object
          properties:
            next:
              type: string
              description: Run ID for next page
            previous:
              type: string
              description: Run ID for previous page

    Schedule:
      type: object
      required: [id, task]
      properties:
        id:
          type: string
          description: Schedule identifier (prefixed with sched_)
        task:
          type: string
          description: The task identifier that this schedule triggers
        type:
          type: string
          enum: [IMPERATIVE, DECLARATIVE]
        active:
          type: boolean
          description: Whether the schedule is active
        deduplicationKey:
          type: string
        externalId:
          type: string
          description: Custom external identifier
        timezone:
          type: string
          description: IANA timezone identifier
        nextRun:
          type: string
          format: date-time
          description: Next scheduled execution time
        generator:
          type: object
          properties:
            type:
              type: string
            expression:
              type: string
              description: Cron expression
            description:
              type: string
        environments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              type:
                type: string

    CreateScheduleRequest:
      type: object
      required: [task, cron, deduplicationKey]
      properties:
        task:
          type: string
          description: Task identifier to trigger
        cron:
          type: string
          description: CRON expression (e.g., "0 9 * * MON-FRI")
        deduplicationKey:
          type: string
          description: Prevents duplicate schedule creation
        externalId:
          type: string
          description: Custom external identifier
        timezone:
          type: string
          description: IANA timezone (defaults to UTC)

    UpdateScheduleRequest:
      type: object
      properties:
        cron:
          type: string
        timezone:
          type: string
        externalId:
          type: string

    Deployment:
      type: object
      properties:
        id:
          type: string
          description: Deployment identifier
        version:
          type: string
          description: Deployment version string
        status:
          type: string
          enum: [PENDING, BUILDING, DEPLOYING, DEPLOYED, FAILED]
        createdAt:
          type: string
          format: date-time
        deployedAt:
          type: string
          format: date-time
        tasks:
          type: array
          items:
            type: object
            properties:
              identifier:
                type: string
              filePath:
                type: string

    Queue:
      type: object
      properties:
        name:
          type: string
          description: Queue name
        paused:
          type: boolean
          description: Whether the queue is paused
        concurrencyLimit:
          type: integer
          description: Maximum concurrent runs
        currentConcurrency:
          type: integer
          description: Currently executing runs
        depth:
          type: integer
          description: Queued runs waiting to execute

    EnvVar:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Variable name
        value:
          type: string
          description: Variable value (may be redacted)

    CreateEnvVarRequest:
      type: object
      required: [name, value]
      properties:
        name:
          type: string
        value:
          type: string

    WaitpointToken:
      type: object
      properties:
        id:
          type: string
          description: Waitpoint token identifier
        status:
          type: string
          enum: [PENDING, COMPLETED, EXPIRED, CANCELLED]
        expiresAt:
          type: string
          format: date-time
          description: Token expiry time
        completedAt:
          type: string
          format: date-time
        data:
          description: Completion data returned to the waiting run

    RunEvent:
      type: object
      properties:
        spanId:
          type: string
        parentId:
          type: string
        runId:
          type: string
        message:
          type: string
        startTime:
          type: string
          format: date-time
        duration:
          type: integer
          description: Span duration in nanoseconds
        isError:
          type: boolean
        isPartial:
          type: boolean
        isCancelled:
          type: boolean
        level:
          type: string
          enum: [TRACE, DEBUG, LOG, INFO, WARN, ERROR]
        kind:
          type: string
          enum: [INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER]
        attemptNumber:
          type: integer
        taskSlug:
          type: string
        events:
          type: array
          items:
            type: object
            additionalProperties: true
        style:
          type: object
          properties:
            icon:
              type: string
            variant:
              type: string
            accessory:
              type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: string