API Reference

All endpoints are prefixed with {basePath}/api. The default base path is /, so endpoints are at /api/....

Config

Method	Path	Description
GET	/api/config	Runtime flags the UI needs before signing in

Returns the handler configuration so clients (and the embedded UI) can adapt before any authenticated request is made. This endpoint is registered before the auth middleware, so it is always reachable.

{
  "data": {
    "readOnly": false,
    "authRequired": true
  }
}

Field	Type	Description
readOnly	boolean	When true, all mutation endpoints reject with 403
authRequired	boolean	When true, an auth callback is configured on the handler

Queues

Method	Path	Description
GET	/api/queues	List all queues (filtered by queues option if set)
GET	/api/queues/:name	Queue detail: job counts and paused job names
POST	/api/queues/:name/pause	Pause a queue or a specific job name
POST	/api/queues/:name/resume	Resume a queue or a specific job name
POST	/api/queues/:name/drain	Drain all waiting and delayed jobs
POST	/api/queues/:name/clean	Remove jobs in a given state older than a grace period
POST	/api/queues/:name/retry	Retry all failed or completed jobs
POST	/api/queues/:name/promote	Promote all delayed jobs to waiting
DELETE	/api/queues/:name	Obliterate a queue (use ?force=true to force)

Pause / Resume Body

{ "jobName": "send-email" }

Omit jobName (or set to "__all__") to pause/resume the entire queue.

Clean Body

{ "state": "completed", "grace": 3600000 }

grace is in milliseconds. Removes jobs in the given state older than the grace period.

Retry Body

{ "state": "failed" }

state must be "failed" or "completed".

Jobs

Method	Path	Description
GET	/api/queues/:name/jobs	List jobs with pagination
POST	/api/queues/:name/jobs	Add a new job
GET	/api/queues/:name/jobs/:id	Job detail
GET	/api/queues/:name/jobs/:id/children	List child jobs (flow)
POST	/api/queues/:name/jobs/:id/retry	Retry a single failed/completed job
POST	/api/queues/:name/jobs/:id/promote	Promote a single delayed job to waiting
POST	/api/queues/:name/jobs/:id/cancel	Cancel an active job
PATCH	/api/queues/:name/jobs/:id	Edit job payload or priority
DELETE	/api/queues/:name/jobs/:id	Remove a job

List Jobs Query Parameters

Parameter	Default	Description
state	waiting	Job state to filter by
start	0	Pagination offset
end	100	Pagination end index (max page size: 1000)

Add Job Body

{
  "name": "send-email",
  "data": { "to": "user@example.com" },
  "opts": { "priority": 1, "delay": 5000 }
}

Edit Job Body

{
  "data": { "to": "updated@example.com" },
  "opts": { "priority": 2 }
}

Cannot edit active jobs.

Groups

Method	Path	Description
GET	/api/queues/:name/groups	List distinct groups with active/waiting counts

Flows

Method	Path	Description
GET	/api/flows	List flow parent jobs

Query Parameters

Parameter	Default	Description
state	all	Filter by job state

Search

Method	Path	Description
GET	/api/search	Quick lookup — job by ID, queue by name, job name, or payload
GET	/api/jobs/search	Advanced job search with combinable filters and pagination

Quick Search Query Parameters (/api/search)

Parameter	Required	Description
q	yes	Search term (job ID, queue name substring, job name substring, or payload text)
type	no	"job" (default), "queue", "name", or "payload"
queue	for payload; optional for name	Queue name to restrict the search

Advanced Search Query Parameters (/api/jobs/search)

Parameter	Default	Description
name	—	Case-insensitive substring match on job name
queue	all allowed queues	Restrict to a specific queue
state	all	Comma-separated JobState list (e.g. waiting,failed) — 400 if none are valid
after	—	ISO 8601 date; jobs created at/after
before	—	ISO 8601 date; jobs created at/before
start	0	Pagination offset
end	50	Pagination end index (max page size: 1000)

Returns a paginated response. Results are ordered by createdAt descending across all three backends (memory, PostgreSQL, SQLite).

Metrics

Method	Path	Description
GET	/api/queues/:name/metrics	Per-queue metrics buckets
GET	/api/metrics/sparklines	Batch sparklines for all queues
GET	/api/metrics/status	Check if metrics are enabled

Metrics Query Parameters

Parameter	Default	Description
granularity	minute	"minute" or "hour"
from	1 hour ago	ISO 8601 date string
to	now	ISO 8601 date string

SSE Events

Method	Path	Description
GET	/api/events	SSE stream for all queues
GET	/api/queues/:name/events	SSE stream for a single queue

The SSE stream sends a connected event on connection, then real-time events as they occur.

Event Types

Event	Description
connected	Initial connection confirmation
job:waiting	Job moved to waiting state
job:active	Job picked up by a worker
job:completed	Job completed successfully
job:failed	Job failed
job:delayed	Job delayed
job:removed	Job removed
job:progress	Job progress updated
job:stalled	Job detected as stalled
job:cancelled	Active job cancelled
queue:paused	Queue or job name paused
queue:resumed	Queue or job name resumed
queue:drained	Queue drained

SSE Client Example

const events = new EventSource('/api/events');

events.addEventListener('job:completed', (e) => {
  const event = JSON.parse(e.data);
  console.log(`Job ${event.jobId} completed in queue ${event.queueName}`);
});

events.addEventListener('job:failed', (e) => {
  const event = JSON.parse(e.data);
  console.log(`Job ${event.jobId} failed: ${event.data?.reason}`);
});

Response Format

Success (single item)

{
  "data": { ... }
}

Success (paginated)

{
  "data": [ ... ],
  "meta": {
    "total": 42,
    "start": 0,
    "end": 100
  }
}

Error

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "state must be \"failed\" or \"completed\""
  }
}

Common error codes: BAD_REQUEST, NOT_FOUND, FORBIDDEN (read-only mode), UNAUTHORIZED (auth failed), METRICS_DISABLED.

OpenAPI Specification

The complete OpenAPI 3.1 spec is available at /openapi.json.

You can import it into tools like Swagger Editor or Scalar for an interactive API explorer.