Enqueue over HTTP.

River supports polyglot insertion, and apalis-board’s only mutation is enqueue — yet the first draft of this spec had no way to enqueue at all. This is how a Python or TypeScript service submits work without a native client, and how an operator re-submits a repaired payload. Requires Idempotency-Key: a retried POST must not create a second job.

An embedding application may install ordered enqueue middleware. The first registered component is outermost; it may mutate an owned envelope copy or veto before authorization/store I/O, and terminal errors unwind in reverse order. Direct enqueue and manual periodic run use the same configured chain.

An embedding application may install a per-kind EnqueueAuthorizer. Authentication happens upstream and supplies an established identity; headgate never trusts an identity header. The backward-compatible default is allow-all. A policy rejection happens before store I/O and returns the structured 403 below.

An optional process-local availability circuit is evaluated after authorization. It counts only typed store-unavailable results; backpressure and other policy responses prove the store is reachable. An open or probe-saturated circuit does no store I/O and returns the structured 503 below.

Embedders may also install non-wrapping insert hooks. After authorization and a circuit permit, each actual store attempt emits one begin and one end event in registration order, including duplicate and id-conflict results. Middleware retries create one hook lifecycle per store attempt; pre-store vetoes create none.

POST /jobs

Error

A valid request URL is required to generate request examples

Headers

Idempotency-Key · string · required

Required on every mutating request. A double-clicked Retry, or a proxy retrying a POST, must not enqueue the job twice. Keys are retained long enough to cover a client retry window and the response is replayed verbatim.

Body

application/json

kind · string · required

payload · string · required

schema_version · integer · default: 1

queue · string · default: default

priority · integer

partition_key · string

rate_class · string

weight · integer · default: 1

Estimated rate-budget cost; unrelated to queue-selection weight.

Required range: x >= 1

scheduled_at_ms · integer

unique_key · string

unique_window_ms · integer

Required range: x >= 0

unique_debounce_ms · integer

Trailing-edge coalescing window measured from store time; replaces payload and tags on conflict.

Required range: x >= 0

unique_exclude_kind · boolean · default: false

Use a fleet-global uniqueness namespace instead of the default kind-scoped namespace.

tags · string[]

Maximum array length: 32

Required string length: 1 - 64

pending · boolean · default: false

Insert durably but keep ineligible until operator promotion.

sticky_worker · string

Exact stable worker identity allowed to claim the job; empty means any worker.

Maximum string length: 255

unique_replace · integer

Bitmask allowlist for replacing an existing non-running unique holder — payload bundle=1, scheduled_at_ms=2, priority=4, max_attempts=8.

Required range: 0 <= x <= 15

Response

201

Enqueued