#HTTP API reference

This page is generated from the route table in @worker-manager/api. Do not edit it by hand: run yarn workspace @worker-manager/api openapi instead. The same content is browsable as an interactive reference, and machine-readable at openapi.json.

The dashboard's own UI is a client of this API and nothing else, so anything the UI can do is available here. Every route is served relative to the base path you passed to setBasePath(). A board mounted at /admin/queues serves GET /admin/queues/api/queues.

#Authentication

There is none. Worker Manager does not authenticate requests and never has: the board inherits whatever protects the route it is mounted on, which is your application's own middleware. See basic auth for the standalone case, and access control hooks for per-route rules.

This matters when pointing a script or an agent at a running board. You send whatever credential your own middleware expects, as an ordinary header, and Worker Manager neither issues nor validates it.

#What can reject a call

A route existing in this document does not mean a given board will answer it.

• Queues registered with readOnlyMode reject every write with 405 and ERRORS.QUEUE_READ_ONLY.
• A visibility guard makes a queue answer 404 as though it were not registered.
• A handlerHooks.before hook can reject any call, by default with 403 and ERRORS.FORBIDDEN.
• The four /api/metrics/* routes are registered only when a historyProvider is configured, and individually only when the provider implements the matching capability. Without one they are not mounted at all and answer 404. See historical metrics.

#Request validation

Every query string and request body documented here is checked against its schema before the route runs, and a request that does not match is refused with 400 before anything is read or written. The check runs after handlerHooks.before, so a hook that hides a route still answers first and a malformed request cannot be used to discover that a hidden route exists.

Query values arrive as strings and are coerced by the schema, which is why parameters such as page document a string alongside a number: the wire carries page=2 and the handler receives 2. An empty value reads as an omitted one, so ?page= is the same request as no page at all.

#Error bodies

Every failure returns ErrorResponseBody. Its error field is a translation key rather than a sentence, because the API never puts user-facing English in a response and the client owns the wording. code is the stable identifier to branch on when you handle a specific failure rather than display it.

{
  "error": { "key": "ERRORS.QUEUE_NOT_FOUND" },
  "message": { "key": "ERRORS.JOB_IS_ACTIVE_DETAILS", "options": { "jobId": "42" } },
  "code": "JOB_BELONGS_TO_JOB_SCHEDULER"
}

#Response shapes

Every response documented here is derived from the same schema the handler is type-checked against, so a handler that stops returning what it advertises does not compile. A board can also check its responses at runtime with options.validateResponses, which is meant for developing a custom adapter or hook rather than for production.

#Versioning

The info.version in the spec describes the shape of this HTTP API and is deliberately independent of the @worker-manager/api package version, so a routine release does not churn the generated artifacts.

#Queues

Board-level and per-queue operations. GET /api/queues is the one the dashboard polls: it returns counts for every queue the request may see, and the jobs of only the queue named in activeQueue, paged by page and jobsPerPage. Everything else here acts on a single queue named in the path, and is refused with 405 when that queue was registered read-only.

#GET /api/queues

List every visible queue with its job counts, and the jobs of the active queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueuesResponse.

#GET /api/queues/{queueName}/metrics

Read the BullMQ completed and failed counter metrics of one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueueMetricsResponse.

#GET /api/queues/{queueName}/default-job-options

Read the default job options configured on one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueueDefaultJobOptionsResponse.

#GET /api/queues/{queueName}/workers

List the workers currently consuming one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueueWorkersResponse.

#GET /api/queues/{queueName}/rate-limit

Read the configured rate limit of one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueueRateLimitResponse.

#PUT /api/queues/{queueName}/rate-limit

Set the rate limit of one queue.

Available only when: The board runs engine 'bullmq', the default.

Request body: SetRateLimitBody

Responds 200 with EmptyResponse.

#GET /api/queues/{queueName}/job-data-schema

Read the JSON Schema describing the job data of one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetQueueJobDataSchemaResponse.

#PUT /api/queues/pause

Pause every writable queue on the board.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/resume

Resume every writable queue on the board.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#POST /api/queues/{queueName}/add

Add a job to one queue.

Available only when: The board runs engine 'bullmq', the default.

Request body: AddJobBody

Responds 200 with AddJobResponse.

#PUT /api/queues/{queueName}/retry/{queueStatus}

Retry every job of one queue in the given status.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with RetryAllResponse.

#PUT /api/queues/{queueName}/promote

Promote every delayed job of one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/clean/{queueStatus}

Remove every job of one queue in the given status.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/pause

Pause one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/resume

Resume one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/concurrency

Set the global concurrency limit of one queue.

Available only when: The board runs engine 'bullmq', the default.

Request body: SetGlobalConcurrencyBody

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/rate-limit/release

Release an active rate limit on one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/empty

Remove every job from one queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/obliterate

Obliterate one queue, removing the queue itself along with all of its jobs.

Available only when: The board runs engine 'bullmq', the default.

Request body: ObliterateQueueBody

Responds 200 with EmptyResponse.

#Jobs

Reads and mutations for one job, addressed by its queue and id. Removing a job that is the pending run of a job scheduler is refused with 400 and the JOB_BELONGS_TO_JOB_SCHEDULER code, because deleting it alone would leave the schedule registered but unable to fire again.

#GET /api/queues/{queueName}/{jobId}/logs

Read the logs of one job.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetJobLogsResponse.

#GET /api/queues/{queueName}/{jobId}/flow

Read the flow tree one job belongs to.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetJobFlowResponse.

#GET /api/queues/{queueName}/{jobId}

Read one job and its current status.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetJobResponse.

#PUT /api/queues/{queueName}/{jobId}/retry

Retry one job.

Available only when: The board runs engine 'bullmq', the default.

Responds 204 with no body.

#PUT /api/queues/{queueName}/{jobId}/clean

Remove one job.

Available only when: The board runs engine 'bullmq', the default.

Responds 204 with no body.

#PUT /api/queues/{queueName}/{jobId}/promote

Promote one delayed job.

Available only when: The board runs engine 'bullmq', the default.

Responds 204 with no body.

#PATCH /api/queues/{queueName}/{jobId}/update-data

Replace the data of one job.

Available only when: The board runs engine 'bullmq', the default.

Request body: UpdateJobDataBody

Responds 200 with EmptyResponse.

#PATCH /api/queues/{queueName}/{jobId}/delay

Reschedule one delayed job.

Available only when: The board runs engine 'bullmq', the default.

Request body: ChangeJobDelayBody

Responds 200 with EmptyResponse.

#PATCH /api/queues/{queueName}/{jobId}/priority

Change the priority of one job.

Available only when: The board runs engine 'bullmq', the default.

Request body: ChangeJobPriorityBody

Responds 200 with EmptyResponse.

#PUT /api/queues/{queueName}/{jobId}/remove-unprocessed-children

Remove the unprocessed children of one job.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with RemoveUnprocessedChildrenResponse.

#Job schedulers

Repeatable job definitions, meaning the schedule itself rather than the runs it produces. Listing spans every visible queue unless you name one. Editing a schedule replaces it, so a body that sets neither a cron pattern nor an interval is rejected.

#GET /api/job-schedulers

List job schedulers across every visible queue, or one named queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetJobSchedulersResponse.

#PUT /api/queues/{queueName}/job-schedulers/{schedulerId}/remove

Remove one job scheduler.

Available only when: The board runs engine 'bullmq', the default.

Responds 204 with no body.

#PATCH /api/queues/{queueName}/job-schedulers/{schedulerId}

Update the schedule of one job scheduler.

Available only when: The board runs engine 'bullmq', the default.

Request body: UpdateJobSchedulerBody

Responds 204 with no body.

#PUT /api/queues/{queueName}/job-schedulers/{schedulerId}/run

Run one job scheduler now, leaving its schedule untouched.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with RunJobSchedulerResponse.

#Metrics history

Long-retention counter and latency history. These routes exist only on a board configured with a historyProvider, and each one individually only when the provider implements the matching capability, so on a board without one they are not mounted and answer 404.

#GET /api/metrics/history

Read recorded job counter history over a time range.

Available only when: A historyProvider is configured on the board.

Responds 200 with GetMetricsHistoryResponse.

#GET /api/metrics/history/usage

Report how much storage the recorded history occupies.

Available only when: A historyProvider is configured on the board. The provider implements getUsage.

Responds 200 with GetMetricsHistoryUsageResponse.

#POST /api/metrics/history/purge

Delete recorded history.

Available only when: A historyProvider is configured on the board. The provider implements purge and the board is not read-only.

Request body: PurgeMetricsHistoryBody

Responds 200 with PurgeMetricsHistoryResponse.

#GET /api/metrics/latency

Read recorded runtime or wait-time latency percentiles over a time range.

Available only when: A historyProvider is configured on the board. The provider implements getLatency.

Responds 200 with GetMetricsLatencyResponse.

#pg-boss

Every route of a board created with engine 'pg-boss' (createPgBossBoard from @worker-manager/pg-boss). Such a board registers these, the metrics history routes and the entry page, and none of the BullMQ routes; a BullMQ board registers none of these. Reads are SQL against the pg-boss schema, writes go through the pg-boss API. Mutations are not registered on a read-only board, and answer 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard keeps writes off. Stable since 2.4.0: this part of the contract follows semver, so a breaking change only ships in a major.

#GET /api/pg-boss/info

Report the pg-boss installation, the schema guard and what the board can do.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossInfoResponse.

#GET /api/pg-boss/queues

List every visible pg-boss queue with its cached counters.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossQueuesResponse.

#GET /api/pg-boss/queues/{queueName}

Read one pg-boss queue.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossQueueResponse.

#GET /api/pg-boss/queues/{queueName}/counts

Count the jobs of one queue in each state, live and capped.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossStateCountsResponse.

#GET /api/pg-boss/queues/{queueName}/depth

Chart one queue's depth over time from pg-boss's own queue_stats snapshots, bucketed.

Available only when: The board was created with engine 'pg-boss'. Answers 409 ERRORS.PGBOSS_FEATURE_UNAVAILABLE on a schema without queue_stats.

Responds 200 with GetPgBossQueueDepthResponse.

#GET /api/pg-boss/queues/{queueName}/jobs

List the jobs of one queue, newest first, one keyset page at a time.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossJobsResponse.

#POST /api/pg-boss/queues/{queueName}/jobs

Send a job to one queue.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: SendPgBossJobBody

Responds 200 with SendPgBossJobResponse.

#GET /api/pg-boss/queues/{queueName}/jobs/{jobId}

Read one job with its data and output.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossJobResponse.

#GET /api/pg-boss/queues/{queueName}/jobs/{jobId}/dependencies

List the jobs one job waits on and the jobs waiting on it.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossDependenciesResponse.

#GET /api/pg-boss/jobs/{jobId}

Find a job by id in whichever visible queue holds it, probing each queue on its primary key.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with FindPgBossJobResponse.

#GET /api/pg-boss/warnings

List pg-boss's persisted warnings, newest first, one keyset page at a time. Warnings naming a hidden queue are left out.

Available only when: The board was created with engine 'pg-boss'. Answers 409 ERRORS.PGBOSS_FEATURE_UNAVAILABLE on a schema without the warning table.

Responds 200 with GetPgBossWarningsResponse.

#GET /api/pg-boss/schedules

List the schedules of every visible queue, or one named queue.

Available only when: The board was created with engine 'pg-boss'.

Responds 200 with GetPgBossSchedulesResponse.

#POST /api/pg-boss/schedules/preview

Work out the next occurrences of a cron or RRULE expression.

Available only when: The board was created with engine 'pg-boss'. Needs pg-boss 12.31 or later, else 409 ERRORS.PGBOSS_PREVIEW_UNAVAILABLE.

Request body: PreviewPgBossScheduleBody

Responds 200 with PreviewPgBossScheduleResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/retry

Retry failed jobs, up to 100 ids at once.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: PgBossJobIdsBody

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/{jobId}/retry

Retry one failed job.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/cancel

Cancel jobs that have not finished, up to 100 ids at once.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: PgBossJobIdsBody

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/{jobId}/cancel

Cancel one job that has not finished. A running handler is not interrupted.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/resume

Resume cancelled jobs, up to 100 ids at once.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: PgBossJobIdsBody

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/{jobId}/resume

Resume one cancelled job.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/remove

Delete jobs, up to 100 ids at once.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: PgBossJobIdsBody

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/jobs/{jobId}/remove

Delete one job that is not active.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/retry-failed

Retry every failed job of one queue.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/delete-queued

Delete every job of one queue that has not started.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/delete-stored

Delete every completed, cancelled and failed job of one queue.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Responds 200 with PgBossCommandResponse.

#PUT /api/pg-boss/queues/{queueName}/schedules

Create or replace the schedule with this key on one queue.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: UpsertPgBossScheduleBody

Responds 200 with PgBossScheduleResponse.

#PUT /api/pg-boss/queues/{queueName}/schedules/remove

Remove one schedule.

Available only when: The board was created with engine 'pg-boss'. The board is not read-only. Answers 409 ERRORS.PGBOSS_WRITES_DISABLED while the schema guard has writes off.

Request body: RemovePgBossScheduleBody

Responds 200 with PgBossCommandResponse.

#Datastore

Statistics for the datastore behind the board's first registered queue. Answers 404 when that queue is backed by something other than Redis that cannot report them, and 403 when the board sets hideRedisDetails.

#GET /api/redis/stats

Read the datastore statistics of the board's first visible queue.

Available only when: The board runs engine 'bullmq', the default.

Responds 200 with GetRedisStatsResponse.

#Schemas

#AppJob

#AppJobScheduler

#AppQueue

#ErrorResponseBody

#ExternalJobUrl

#FlowDependencies

#FlowNode

#JobCounts

object

#JobFlow

#JobState

latest` \| `active` \| `waiting` \| `waiting-children` \| `prioritized` \| `completed` \| `failed` \| `delayed` \| `paused` \| `stuck` \| `unknown

#JobStatus

active` \| `waiting` \| `waiting-children` \| `prioritized` \| `completed` \| `failed` \| `delayed` \| `paused

#MetricsHistoryGranularity

hour` \| `day

#MetricsHistoryMetric

completed` \| `failed` \| `queueage

#MetricsLatencyGranularity

hour` \| `day` \| `range

#MetricsLatencyMetric

runtime` \| `waittime

#MetricsHistoryPoint

#MetricsHistoryPurgeResult

#MetricsHistoryQueueUsage

#MetricsHistoryTierUsage

#MetricsHistoryUsage

#MetricsLatencyPoint

#Pagination

#QueueType

bull` \| `bullmq

#QueueLibrary

bull` \| `bullmq` \| `bullmq-pro

#QueueCapabilities

#JobSchedulerKind

every` \| `cron

#Datastore

redis` \| `postgres

#Status

latest` \| `active` \| `waiting` \| `waiting-children` \| `prioritized` \| `completed` \| `failed` \| `delayed` \| `paused

#QueueDefaultJobOptions

#QueueMetrics

#QueueRateLimit

#QueueWorker

#RedisStats

#TranslatableMessage

#PgBossJobState

created` \| `retry` \| `active` \| `completed` \| `cancelled` \| `failed

#PgBossQueueCounts

#PgBossQueueSummary

#PgBossStateCount

#PgBossStateCounts

#PgBossDeadLetterSource

#PgBossJobSummary

#PgBossJob

#PgBossDependencyRef

#PgBossScheduleKind

cron` \| `rrule

#PgBossSchedule

#PgBossCapabilities

#PgBossFeature

queueCounters` \| `readyHistory` \| `schedules` \| `scheduleKind` \| `dependencies` \| `deadLetterSource` \| `queueDepth` \| `warnings

#PgBossFeatures

#PgBossInfo

#PgBossQueueDepthPoint

#PgBossWarning

#GetQueuesResponse

#GetJobResponse

#AddJobResponse

#GetQueueMetricsResponse

#GetQueueDefaultJobOptionsResponse

#GetQueueJobDataSchemaResponse

object

#GetQueueRateLimitResponse

#GetQueueWorkersResponse

#GetJobSchedulersResponse

#RunJobSchedulerResponse

#GetJobLogsResponse

string[]

#GetJobFlowResponse

#GetRedisStatsResponse

RedisStats \| object

#GetMetricsHistoryResponse

#GetMetricsHistoryUsageResponse

#GetMetricsLatencyResponse

MetricsLatencyPoint[]

#PurgeMetricsHistoryResponse

#RetryAllResponse

#RemoveUnprocessedChildrenResponse

#JobBelongsToJobSchedulerResponse

#EmptyResponse

#GetPgBossInfoResponse

#GetPgBossQueuesResponse

#GetPgBossQueueResponse

#GetPgBossStateCountsResponse

#GetPgBossJobsResponse

#GetPgBossJobResponse

#FindPgBossJobResponse

#GetPgBossQueueDepthResponse

#GetPgBossWarningsResponse

#GetPgBossDependenciesResponse

#GetPgBossSchedulesResponse

#PreviewPgBossScheduleResponse

#SendPgBossJobResponse

#PgBossCommandResponse

#PgBossScheduleResponse

#GetQueuesQuery

#GetJobSchedulersQuery

#GetJobFlowQuery

#GetMetricsHistoryQuery

#GetMetricsLatencyQuery

#AddJobBody

#UpdateJobDataBody

#ChangeJobDelayBody

#ChangeJobPriorityBody

#SetGlobalConcurrencyBody

#SetRateLimitBody

object \| object

#ObliterateQueueBody

#UpdateJobSchedulerBody

#PurgeMetricsHistoryBody

#GetPgBossJobsQuery

#GetPgBossSchedulesQuery

#GetPgBossQueueDepthQuery

#GetPgBossWarningsQuery

#PreviewPgBossScheduleBody

#SendPgBossJobBody

#PgBossJobIdsBody

#UpsertPgBossScheduleBody

#RemovePgBossScheduleBody