REST API

Every operation of /api/v1, from the OpenAPI document the server serves at GET /api/v1/openapi.json (this page lists the Pro routes too; a server without a Pro key leaves them out of its document). The SDK gateway has its own document at GET /api/v1/sdk/openapi.json.

• Authentication. Authorization: Bearer <token>, or the console's session cookie plus X-Requested-With: joobqui on state-changing calls. The /api/v1/sdk/* routes take Authorization: Bearer $JOOBQUI_SDK_TOKEN instead.
• Role. The least role of each operation (viewer < operator < admin); too low a role answers 403 forbidden_role. See Roles and permissions.
• Errors. Always {"error": {code, message, details, request_id}}; see Error codes.
• Pro. Pro marks an operation that answers 402 pro_required without a JoobQ Pro key, or that the server registers only with one; see the Pro features index.

/accounts

POST /api/v1/accounts

Sign up for an account, where sign-up is open or by invite

• Role: none (public)
• Success: 201
• Body:

Field	Type	Required
email	any
invite	any
password	any
username	any

/alerts

GET /api/v1/alerts Pro

Alert overview: active alerts, rules and recent history

• Role: viewer
• Success: 200

GET /api/v1/alerts/active Pro

List the alerts firing now

• Role: viewer
• Success: 200

GET /api/v1/alerts/history Pro

Page through past alerts

• Role: viewer
• Success: 200

GET /api/v1/alerts/options Pro

What alert rules can watch and notify

• Role: viewer
• Success: 200

GET /api/v1/alerts/rules Pro

List the alert rules

• Role: viewer
• Success: 200

POST /api/v1/alerts/rules Pro

Create an alert rule

• Role: operator
• Success: 200
• Body:

Field	Type	Required
description	any
duration_seconds	any
metric	any
name	any
operator	any
queue	any
severity	any
threshold	any

DELETE /api/v1/alerts/rules/:id Pro

Delete an alert rule

• Role: operator
• Success: 200

PUT /api/v1/alerts/rules/:id Pro

Enable or disable an alert rule

• Role: operator
• Success: 200
• Body:

Field	Type	Required
enabled	any

POST /api/v1/alerts/:id/acknowledge Pro

Acknowledge an alert

• Role: operator
• Success: 200

/audit

GET /api/v1/audit

Search the audit log, or download the selection

• Role: admin
• Success: 200

/capabilities

GET /api/v1/capabilities

What this server can do and its limits

• Role: none (public)
• Success: 200

/dlq

GET /api/v1/dlq

Page through the dead letters, newest first

• Role: viewer
• Success: 200

POST /api/v1/dlq/purge

Delete dead letters by jid, or all of them (optionally one queue's)

• Role: operator
• Success: 200
• Body:

Field	Type	Required
all	any
jids	any
queue	any

POST /api/v1/dlq/redrive

Re-drive dead letters back onto their queues

• Role: operator
• Success: 200
• Body:

Field	Type	Required
jids	any

/email

POST /api/v1/email/resend

Send the verification email again

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
email	any

POST /api/v1/email/verify

Confirm an email address with its token

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
token	any

/export

GET /api/v1/export/dlq

Download the dead letters as CSV or JSON

• Role: viewer
• Success: 200

GET /api/v1/export/queues

Download the queue list as CSV or JSON

• Role: viewer
• Success: 200

/jobs

GET /api/v1/jobs

Page through jobs in one state, optionally of one queue

• Role: viewer
• Success: 200

POST /api/v1/jobs/delete

Delete jobs in bulk

• Role: operator
• Success: 200
• Body:

Field	Type	Required
jids	any
queue	any
state	any

POST /api/v1/jobs/retry

Retry jobs in bulk (a dead job is re-driven, a delayed one runs now)

• Role: operator
• Success: 200
• Body:

Field	Type	Required
jids	any
queue	any
state	any

DELETE /api/v1/jobs/:jid

Delete one job

• Role: operator
• Success: 200

GET /api/v1/jobs/:jid

Find a job by its jid

• Role: viewer
• Success: 200

POST /api/v1/jobs/:jid/retry

Retry one job

• Role: operator
• Success: 200

/notification-channels

GET /api/v1/notification-channels

List the notification channels

• Role: admin
• Success: 200

POST /api/v1/notification-channels

Create a notification channel

• Role: admin
• Success: 200
• Body:

Field	Type	Required
email	any
enabled	any
kind	any
min_severity	any
name	any
secret	any
url	any

DELETE /api/v1/notification-channels/:id

Delete a notification channel

• Role: admin
• Success: 200

GET /api/v1/notification-channels/:id

Show one notification channel

• Role: admin
• Success: 200

PUT /api/v1/notification-channels/:id

Change a notification channel

• Role: admin
• Success: 200
• Body:

Field	Type	Required
email	any
enabled	any
kind	any
min_severity	any
name	any
secret	any
url	any

POST /api/v1/notification-channels/:id/test

Send a test notification through a channel

• Role: admin
• Success: 200

/openapi.json

GET /api/v1/openapi.json

The OpenAPI 3.1 description of this API

• Role: none (public)
• Success: 200

/password

POST /api/v1/password/forgot

Ask for a password reset link by email

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
email	any

POST /api/v1/password/reset

Set a new password with a reset token

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
password	any
token	any

/queues

GET /api/v1/queues

List the queues with their sizes and workers

• Role: viewer
• Success: 200

POST /api/v1/queues/:name/clear

Delete every waiting job of a queue

• Role: operator
• Success: 204

PUT /api/v1/queues/:name/concurrency

Ask the workers for a different concurrency on a queue

• Role: operator
• Success: 204
• Body:

Field	Type	Required
concurrency	integer	yes

GET /api/v1/queues/:name/jobs

Page through a queue's waiting jobs

• Role: viewer
• Success: 200

POST /api/v1/queues/:name/pause

Pause a queue: workers stop taking its jobs

• Role: operator
• Success: 204

POST /api/v1/queues/:name/resume

Resume a paused queue

• Role: operator
• Success: 204

DELETE /api/v1/queues/:name/throttle

Remove the throttle set on a queue from the console or the API

• Role: operator
• Success: 204

PUT /api/v1/queues/:name/throttle

Throttle a queue that only SDK workers serve: at most limit claims per period_ms

• Role: operator
• Success: 204
• Body:

Field	Type	Required
limit	integer	yes
period_ms	integer	yes

/schedules

GET /api/v1/schedules

List the configured schedules

• Role: viewer
• Success: 200

GET /api/v1/schedules/:id

Show one schedule

• Role: viewer
• Success: 200

POST /api/v1/schedules/:id/pause

Pause a schedule

• Role: operator
• Success: 200

POST /api/v1/schedules/:id/resume

Resume a paused schedule

• Role: operator
• Success: 200

POST /api/v1/schedules/:id/run

Enqueue one run of a schedule now

• Role: operator
• Success: 200

/session

DELETE /api/v1/session

Sign out

• Role: viewer (allowed before a required second factor is enrolled)
• Success: 204

GET /api/v1/session

Who the caller is and their role

• Role: viewer (allowed before a required second factor is enrolled)
• Success: 200

POST /api/v1/session

Sign in with a username or email and a password

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
password	any
user	any

POST /api/v1/session/mfa

Finish a sign-in with a one-time code or a recovery code

• Role: none (public)
• Success: 200
• Body:

Field	Type	Required
challenge	any
code	any

/telemetry

GET /api/v1/telemetry/summary

Headline numbers, throughput and latency percentiles

• Role: viewer
• Success: 200

/tokens

GET /api/v1/tokens

List the API tokens (never the secrets)

• Role: admin
• Success: 200

POST /api/v1/tokens

Create an API token; the secret is shown once, in this answer

• Role: admin
• Success: 201
• Body:

Field	Type	Required
expires_in_days	any
name	string	yes
role	any

DELETE /api/v1/tokens/:id

Revoke an API token

• Role: admin
• Success: 200

/users

GET /api/v1/users

List the accounts

• Role: admin
• Success: 200

PUT /api/v1/users/:id

Change an account's role or switch it on or off (one per call)

• Role: admin
• Success: 200
• Body:

Field	Type	Required
active	any
role	any

/workers

GET /api/v1/workers

List the registered worker processes

• Role: viewer
• Success: 200

/workflow-archive

GET /api/v1/workflow-archive Pro

Runs exported to the archive before retention deleted them, newest first

• Role: viewer
• Success: 200

GET /api/v1/workflow-archive/:id Pro

An archived run: its final state and a page of its events

• Role: viewer
• Success: 200

POST /api/v1/workflow-archive/:id/replay Pro

Replay an archived run's history against the definition registered now

• Role: operator
• Success: 200

/workflow-attributes

GET /api/v1/workflow-attributes Pro

The registered search attributes and their types

• Role: viewer
• Success: 200

POST /api/v1/workflow-attributes Pro

Register a search attribute name with its type

• Role: admin
• Success: 201
• Body:

Field	Type	Required
name	any
type	any

/workflow-builds

GET /api/v1/workflow-builds Pro

The worker build sets, what is pinned to each and whether workers are alive

• Role: viewer
• Success: 200

GET /api/v1/workflow-builds/pinned Pro

How many open runs are pinned to each build set

• Role: viewer
• Success: 200

POST /api/v1/workflow-builds/:build/promote Pro

Start new runs of a workflow on a build

• Role: admin
• Success: 200
• Body:

Field	Type	Required
workflow	string	yes

POST /api/v1/workflow-builds/:build/repin Pro

Move the open runs pinned to a build set onto another build

• Role: admin
• Success: 200

POST /api/v1/workflow-builds/:build/retire Pro

Retire a build for good

• Role: admin
• Success: 204
• Body:

Field	Type	Required
force	boolean

/workflow-definitions

GET /api/v1/workflow-definitions Pro

Search the workflow names that can be started

• Role: viewer
• Success: 200

/workflow-retention

GET /api/v1/workflow-retention Pro

Whether finished workflows are pruned, and what the last pass removed

• Role: viewer
• Success: 200

/workflow-scheduler

GET /api/v1/workflow-scheduler Pro

Whether anything is firing workflow schedules

• Role: viewer
• Success: 200

/workflow-schedules

GET /api/v1/workflow-schedules Pro

List the workflow schedules

• Role: viewer
• Success: 200

POST /api/v1/workflow-schedules Pro

Create a workflow schedule

• Role: admin
• Success: 201

DELETE /api/v1/workflow-schedules/:id Pro

Delete a workflow schedule (runs it started are left alone)

• Role: admin
• Success: 204

GET /api/v1/workflow-schedules/:id Pro

Show one workflow schedule with its next runs

• Role: viewer
• Success: 200

PUT /api/v1/workflow-schedules/:id Pro

Change a workflow schedule (fields left out keep their value)

• Role: admin
• Success: 200

POST /api/v1/workflow-schedules/:id/backfill Pro

Start the runs of the fire times in a past range

• Role: operator
• Success: 200

POST /api/v1/workflow-schedules/:id/pause Pro

Pause a workflow schedule

• Role: operator
• Success: 200

POST /api/v1/workflow-schedules/:id/resume Pro

Resume a paused workflow schedule from now

• Role: operator
• Success: 200

POST /api/v1/workflow-schedules/:id/trigger Pro

Start a run of the schedule now

• Role: operator
• Success: 201

/workflows

GET /api/v1/workflows Pro

Page through workflow runs, newest first

• Role: viewer
• Success: 200

POST /api/v1/workflows Pro

Start a workflow run (a known id is a no-op)

• Role: operator
• Success: 201
• Body:

Field	Type	Required
name	string	yes

POST /api/v1/workflows/bulk Pro

Terminate, cancel, signal or re-drive many workflows at once

• Role: operator
• Success: 200

GET /api/v1/workflows/:id Pro

Show one run with its steps

• Role: viewer
• Success: 200

POST /api/v1/workflows/:id/attributes Pro

Set and remove search attributes of an open run

• Role: operator
• Success: 200
• Body:

Field	Type	Required
remove	any
set	any

POST /api/v1/workflows/:id/cancel Pro

Cancel a running workflow, undoing completed steps that can be undone

• Role: operator
• Success: 204

POST /api/v1/workflows/:id/continue-as-new Pro

Close the open run and start its successor now

• Role: operator
• Success: 201

GET /api/v1/workflows/:id/history Pro

The events of a run

• Role: viewer
• Success: 200

POST /api/v1/workflows/:id/migrate Pro

Move an open run onto the latest definition after a clean replay

• Role: operator
• Success: 200

POST /api/v1/workflows/:id/query Pro

Ask a run a read-only question

• Role: operator
• Success: 200
• Body:

Field	Type	Required
name	string	yes

POST /api/v1/workflows/:id/redrive Pro

Start a new run from a failed, terminated, cancelled or timed-out one

• Role: operator
• Success: 201

POST /api/v1/workflows/:id/repin Pro

Pin an open run to another build

• Role: admin
• Success: 200

POST /api/v1/workflows/:id/replay Pro

Replay a run's history against the definition registered now

• Role: operator
• Success: 200

GET /api/v1/workflows/:id/runs Pro

The runs of the continue-as-new chain a run belongs to

• Role: viewer
• Success: 200

POST /api/v1/workflows/:id/scopes/:scope/cancel Pro

Cancel one cancellation scope of a running workflow

• Role: operator
• Success: 204

POST /api/v1/workflows/:id/signal Pro

Send a signal to a running workflow

• Role: operator
• Success: 204
• Body:

Field	Type	Required
name	string	yes

POST /api/v1/workflows/:id/steps/:step/retry Pro

Retry a failed activity of a running workflow

• Role: operator
• Success: 204

POST /api/v1/workflows/:id/terminate Pro

Terminate a running workflow at once

• Role: operator
• Success: 204

GET /api/v1/workflows/:id/updates/:name Pro

The recorded outcome of an update

• Role: viewer
• Success: 200

POST /api/v1/workflows/:id/updates/:name Pro

Send a validated update to a running workflow and wait for its answer

• Role: operator
• Success: 200

SDK gateway (/api/v1/sdk)

POST /api/v1/sdk/blueprints Pro

Register a workflow blueprint, versioned by its content hash

• Role: operator
• Success: 200
• Body:

Field	Type	Required
blueprint	any
name	string	yes
sdk_language	string	yes
worker_id	string

POST /api/v1/sdk/jobs Pro

Enqueue a background job onto a queue

• Role: operator
• Success: 201
• Body:

Field	Type	Required
context	object
delay_ms	integer
encrypt_fields	array of string
expires_ms	integer
jid	string
job_type	string	yes
max_retries	integer
payload	any
queue	string	yes
run_at_ms	integer
timeout_ms	integer
unique_key	string
unique_mode	string
unique_ttl_ms	integer

POST /api/v1/sdk/jobs/batch Pro

Enqueue up to 500 background jobs in one call

• Role: operator
• Success: 201
• Body:

Field	Type	Required
jobs	array of object

GET /api/v1/sdk/openapi.json

Describe the Polyglot SDK Gateway API as an OpenAPI 3.1 document

• Role: none (public)
• Success: 200

POST /api/v1/sdk/rate-limit Pro

Reserve one slot of a sliding-window rate limit (Pro)

• Role: operator
• Success: 200
• Body:

Field	Type	Required
key	string	yes
limit	integer	yes
period_ms	integer	yes

POST /api/v1/sdk/schedules Pro

Register a code-declared cron/recurring job or workflow schedule, idempotent by name

• Role: operator
• Success: 200
• Body:

Field	Type	Required
cron	string
encrypt_fields	array of string
every	string
input	any
job_type	string
kind	string	yes
max_retries	integer
name	string	yes
payload	any
queue	string
timezone	string
unique_key	string
workflow	string

POST /api/v1/sdk/tasks/ack

Settle up to 100 task leases in one call, each completed or failed

• Role: operator
• Success: 200
• Body:

Field	Type	Required
items	array of object
worker_id	string	yes

POST /api/v1/sdk/tasks/heartbeat

Extend every lease a worker holds in one call and check each for cancellation

• Role: operator
• Success: 200
• Body:

Field	Type	Required
lease_ttl_ms	integer
leases	array of object
worker_id	string	yes

POST /api/v1/sdk/tasks/poll

Claim due jobs and workflow steps from unpaused queues

• Role: operator
• Success: 200
• Body:

Field	Type	Required
lease_ttl_ms	integer
max_tasks	integer
task_queues	array of string	yes
timeout_ms	integer
worker_id	string	yes

POST /api/v1/sdk/tasks/:token/complete

Commit task completion and output

• Role: operator
• Success: 200
• Body:

Field	Type	Required
output	any
worker_id	string	yes

POST /api/v1/sdk/tasks/:token/fail

Record structured polyglot task failure and stack frames

• Role: operator
• Success: 200
• Body:

Field	Type	Required
error_class	string	yes
error_message	string	yes
raw_stacktrace	string
retryable	boolean
sdk_language	string
stack_frames	array of object
worker_id	string	yes

POST /api/v1/sdk/tasks/:token/heartbeat

Extend an active task lease and check for cancellation

• Role: operator
• Success: 200
• Body:

Field	Type	Required
lease_ttl_ms	integer
worker_id	string	yes

POST /api/v1/sdk/workers/register

Register or heartbeat a polyglot SDK worker

• Role: operator
• Success: 200
• Body:

Field	Type	Required
active_leases	integer
callback_url	string
concurrency	integer
cpu_pct	number
delivery_mode	string
host	string
pid	integer
poll_latency_ms	number
rss_kb	integer
sdk_language	string	yes
sdk_version	string
service_name	string
task_queues	array of string	yes
team	string
worker_id	string	yes

POST /api/v1/sdk/workers/:id/deregister

Deregister a polyglot SDK worker on shutdown

• Role: operator
• Success: 200

POST /api/v1/sdk/workflows Pro

Start a durable workflow execution

• Role: operator
• Success: 201
• Body:

Field	Type	Required
build	string
context	object
id	string
input	any
name	string	yes
search_attributes	object

GET /api/v1/sdk/workflows/:id Pro

Describe one workflow run: status, output, failure and search attributes

• Role: viewer
• Success: 200

GET /api/v1/sdk/workflows/:id/history Pro

The events of a workflow run, after after_seq, at most limit

• Role: viewer
• Success: 200

POST /api/v1/sdk/workflows/:id/query Pro

Ask a workflow run a read-only question

• Role: operator
• Success: 200
• Body:

Field	Type	Required
name	string	yes

GET /api/v1/sdk/workflows/:id/result Pro

The outcome of a workflow, following continue-as-new; waits up to wait_ms for it to close

• Role: viewer
• Success: 200

POST /api/v1/sdk/workflows/:id/search-attributes Pro

Set and remove search attributes of a workflow's open run

• Role: operator
• Success: 200
• Body:

Field	Type	Required
remove	any
set	any

POST /api/v1/sdk/workflows/:id/signal Pro

Deliver an asynchronous signal to a running workflow

• Role: operator
• Success: 200
• Body:

Field	Type	Required
name	string	yes
payload	any

POST /api/v1/sdk/workflows/:id/updates Pro

Send an update to a running workflow and wait for its outcome

• Role: operator
• Success: 200
• Body:

Field	Type	Required
input	any
name	string	yes
update_id	string
wait_ms	integer