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 comple
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trigger-dev/refs/heads/main/openapi/trigger-dev-management-openapi.yml