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.0.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: []
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'
# ── 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
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
fo
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trigger-dev/refs/heads/main/openapi/trigger-dev-management-openapi.yml