Skip to content
Artist Alley

Atomically claim a batch of pending jobs

POST
/jobs/claim

Pulls up to limit pending jobs whose type is in the types allowlist (omit types to claim any type the caller is authorised to run). Each claimed job is marked running with a lease — the worker must call /jobs/{id}/heartbeat before the lease expires or the watchdog will requeue it.

Auth: any authenticated caller for now. A future phase adds a worker token kind that scopes claim/complete/fail without granting any read access elsewhere.

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Body for POST /jobs/claim. types is the allowlist of job types this worker is willing to run; omit to claim any. worker_id is a stable string the server records in claimed_by for diagnostic tracing.

object
types
Array<string>
limit
integer
default: 1 >= 1 <= 25
worker_id
string
>= 1 characters <= 200 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Claimed jobs (possibly an empty array)

object
jobs
required
Array<object>

Trimmed view of a Job that workers actually need to execute the work. lease_seconds tells the worker how often to heartbeat before the watchdog reclaims the job.

object
id
required
string format: uuid
type
required
string
payload
required
object
key
additional properties
any
attempts
required
integer
max_attempts
required
integer
lease_seconds
required
integer

401

Section titled “401 ”

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
  "error": "authentication required: sign in and retry with a valid session or API token"
}