API reference
Generated from openapi.yaml, which is the source of truth.
LessorMQ leases each message to one worker at a time. Everything that happens to a message after that is decided by the server, from the settings of its queue: when it is retried, how long it waits, when it is dead-lettered, which route it may not take again, how long it is kept.
A client does four things: publish, claim, then ack or fail (and extend a lease while a long job runs). It may pass settings such as a lease length or a maximum number of attempts; the server applies them within the limits of the queue. A client never decides whether a message is retried.
See the protocol for the concepts, the message lifecycle and the rules a conforming client must follow.
Conventions:
- Every timestamp is RFC 3339 in UTC, with a
Zsuffix. - Every error is
application/problem+json(RFC 9457) with a stablecode. - Clients must ignore response fields they do not know: fields are added within v1, never removed or changed in meaning.
Authentication
Authorization: Bearer <api key>.
A tenant key identifies its tenant; there is no tenant in any path outside
/v1/tenants. Each tenant key has scopes (publish, consume, admin) and may
be limited to queue name patterns.
An operator key belongs to no tenant. It is for whoever runs the installation (a
web interface, a provisioning tool) and is the only key accepted on /v1/tenants.
With the header LessorMQ-Tenant: <tenant id> it may call every other endpoint as
an admin key of that tenant. The first operator key is created on the command
line; there is no endpoint that creates operator keys.
Publishing
Put messages on a queue. Requires the publish scope.
Publish a message
POST /v1/queues/{queue}/messages
Creates the queue with the tenant's default settings if it does not exist yet.
With a dedup_key, a second publish with the same key while the first message is
still open (pending or processing) returns that message with status 200 and
duplicate: true instead of creating a new one. Client libraries may generate a
dedup_key per publish call so that their own HTTP retries cannot create
duplicates.
Publishing to a paused queue is allowed: pausing only stops claims.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
Request body: PublishRequest
| Status | Meaning | Body |
|---|---|---|
| 201 | Message created. | PublishResponse |
| 200 | An open message with the same dedup_key exists; it is returned instead. |
PublishResponse |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 413 | The message is larger than the queue's max_message_bytes. Code payload_too_large. |
Problem |
| 429 | The tenant exceeded a quota or rate limit. Code rate_limited. |
Problem |
Consuming
Claim messages and report the outcome. Requires the consume scope.
Claim the next message
POST /v1/queues/{queue}/claims
Leases the next ready message to the caller and returns it with a receipt. Only
the holder of that receipt can extend, ack, fail or release the message, and only
until lease_until. After that the lease has expired: the server makes the
message available again and counts the attempt.
With wait_seconds, the request waits until a message becomes ready or the time
runs out (long polling). A paused queue behaves as an empty one.
With a route, the server will not hand out a message that already failed on
that route, while the queue's route_policy says so.
Messages are handed out roughly in order of availability; strict ordering is not guaranteed. Delivery is at least once: a handler must tolerate seeing a message again.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
Request body (optional): ClaimRequest
| Status | Meaning | Body |
|---|---|---|
| 200 | A message is leased to the caller. | Lease |
| 204 | No message was ready within wait_seconds, or the queue is paused. |
|
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 429 | The tenant exceeded a quota or rate limit. Code rate_limited. |
Problem |
Extend a lease
POST /v1/messages/{id}/extend
Moves lease_until to now plus lease_seconds (or the queue's default). A worker
calls this while a long job runs; client libraries do it on a timer, at about a
third of the lease.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
Request body: ExtendRequest
| Status | Meaning | Body |
|---|---|---|
| 200 | Lease extended. | ExtendResponse |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The receipt is not the current lease of this message: the lease expired, the message was claimed again, or it was released. The worker must stop reporting on this message; the server has already made it available again. Code lease_lost. |
Problem |
Report success
POST /v1/messages/{id}/ack
Marks the message completed. Idempotent per receipt: repeating an ack with the same receipt returns 204 again.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
Request body: ReceiptRequest
| Status | Meaning | Body |
|---|---|---|
| 204 | Message completed. | |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The receipt is not the current lease of this message: the lease expired, the message was claimed again, or it was released. The worker must stop reporting on this message; the server has already made it available again. Code lease_lost. |
Problem |
Report failure
POST /v1/messages/{id}/fail
Reports that the attempt failed. The server decides what happens next from the
queue settings and tells the caller in outcome; the caller does not act on it.
permanent: true is a fact, not a request: it says the input itself cannot be
processed (for example, it cannot be decoded). The queue's on_permanent setting
decides whether that skips the remaining attempts.
Idempotent per receipt: repeating a fail with the same receipt returns the same outcome, as long as the message has not been claimed again.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
Request body: FailRequest
| Status | Meaning | Body |
|---|---|---|
| 200 | Failure recorded; outcome says what the server did. |
FailResponse |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The receipt is not the current lease of this message: the lease expired, the message was claimed again, or it was released. The worker must stop reporting on this message; the server has already made it available again. Code lease_lost. |
Problem |
Give a message back without failing it
POST /v1/messages/{id}/release
Ends the lease without an outcome, for a worker that has to stop before it can
run the message (shutdown, lost a dependency). The attempt is not counted. The
message is available again after delay_seconds.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
Request body: ReleaseRequest
| Status | Meaning | Body |
|---|---|---|
| 204 | Message released. | |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The receipt is not the current lease of this message: the lease expired, the message was claimed again, or it was released. The worker must stop reporting on this message; the server has already made it available again. Code lease_lost. |
Problem |
Queues
Queue settings and statistics.
List the tenant's queues
GET /v1/queues
Requires the admin scope.
| Status | Meaning | Body |
|---|---|---|
| 200 | All queues of the tenant, with settings and statistics. | object |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Get a queue's settings and statistics
GET /v1/queues/{queue}
Requires the consume or admin scope.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The queue. | Queue |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Change queue settings
PATCH /v1/queues/{queue}
Requires the admin scope. Only the fields present change. Creates the queue if it
does not exist, so settings can be in place before the first publish.
Pausing is a setting too: {"paused": true} stops claims, publishes still land.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
Request body: QueueSettingsPatch
| Status | Meaning | Body |
|---|---|---|
| 200 | The queue with its new settings. | Queue |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Messages
Inspect, replay and delete messages, including the dead-letter set. Requires the admin scope.
List messages of a queue
GET /v1/queues/{queue}/messages
Newest first. Paginated with an opaque cursor.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
status |
query | MessageStatus | |
error_type |
query | string | Only messages whose last error has this type. |
limit |
query | integer (min 1, max 100) | |
cursor |
query | string | The next_cursor of the previous page. |
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of messages. | MessagePage |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Get a message
GET /v1/messages/{id}
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The message. | Message |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Delete a message
DELETE /v1/messages/{id}
A message that is processing cannot be deleted; wait for its lease to end.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
| Status | Meaning | Body |
|---|---|---|
| 204 | Message deleted. | |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
Make a failed or completed message available again
POST /v1/messages/{id}/replay
Puts the message back to pending with its attempts reset to zero and its failed
routes cleared. Only from failed or completed; a pending or processing message
returns 409.
| Parameter | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | Message id as returned by publish or claim. Opaque to clients. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Message is pending again. | Message |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
Replay many messages
POST /v1/queues/{queue}/replay
Replays every message matching the filter, as replayMessage does for one.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
Request body: BulkFilter
| Status | Meaning | Body |
|---|---|---|
| 200 | Number of messages replayed. | BulkResult |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Delete many messages
POST /v1/queues/{queue}/purge
Deletes every message matching the filter. Never touches pending or processing messages.
| Parameter | In | Type | Description |
|---|---|---|---|
queue (required) |
path | QueueName | Queue name, unique within the tenant. |
Request body: BulkFilter
| Status | Meaning | Body |
|---|---|---|
| 200 | Number of messages deleted. | BulkResult |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
API keys
Keys of the calling tenant. Requires the admin scope.
List the tenant's API keys
GET /v1/api-keys
Secrets are never returned after creation; keys are recognised by prefix.
| Status | Meaning | Body |
|---|---|---|
| 200 | All keys of the tenant. | object |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Create an API key
POST /v1/api-keys
The response is the only time the secret is shown. Store it right away.
Request body: ApiKeyCreate
| Status | Meaning | Body |
|---|---|---|
| 201 | Key created. | ApiKeyCreated |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Revoke an API key
DELETE /v1/api-keys/{keyId}
Takes effect immediately. A key cannot revoke itself, so a tenant cannot lock itself out.
| Parameter | In | Type | Description |
|---|---|---|---|
keyId (required) |
path | string |
| Status | Meaning | Body |
|---|---|---|
| 204 | Key revoked. | |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
Tenant
The calling tenant's own profile, quotas and usage. Requires the admin scope.
Get the calling tenant
GET /v1/tenant
| Status | Meaning | Body |
|---|---|---|
| 200 | The tenant the key belongs to. | Tenant |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Change the calling tenant's queue defaults
PATCH /v1/tenant
A tenant may change the defaults for its new queues; its name, status and quotas are the operator's.
Request body: object
| Status | Meaning | Body |
|---|---|---|
| 200 | The tenant with its new defaults. | Tenant |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Tenants
Create and manage tenants, for a web interface or provisioning tool run by whoever operates the installation. Requires an operator key.
List tenants
GET /v1/tenants
| Parameter | In | Type | Description |
|---|---|---|---|
status |
query | TenantStatus | |
limit |
query | integer (min 1, max 100) | |
cursor |
query | string | The next_cursor of the previous page. |
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of tenants. | object |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
Create a tenant
POST /v1/tenants
By default also creates a first API key with all three scopes and returns its secret once, so the interface can hand it to the new tenant.
Request body: TenantCreate
| Status | Meaning | Body |
|---|---|---|
| 201 | Tenant created. | TenantCreated |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
Get a tenant
GET /v1/tenants/{tenantId}
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId |
| Status | Meaning | Body |
|---|---|---|
| 200 | The tenant. | Tenant |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Change a tenant
PATCH /v1/tenants/{tenantId}
Suspending a tenant (status: suspended) makes every request with its keys return
403 tenant_suspended; its messages stay as they are and leases run out normally.
Setting it back to active resumes everything.
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId |
Request body: TenantPatch
| Status | Meaning | Body |
|---|---|---|
| 200 | The tenant after the change. | Tenant |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
Delete a tenant and all its data
DELETE /v1/tenants/{tenantId}
Only a suspended tenant can be deleted, so a tenant in use is never removed by one
call. Its status becomes deleting and its keys, queues and messages are removed
in the background; the tenant disappears when that is done.
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId |
| Status | Meaning | Body |
|---|---|---|
| 202 | Deletion started. | Tenant |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
| 409 | The message or key is in a state that does not allow this. Code invalid_state. |
Problem |
List a tenant's API keys
GET /v1/tenants/{tenantId}/api-keys
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId |
| Status | Meaning | Body |
|---|---|---|
| 200 | All keys of the tenant. | object |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Create an API key for a tenant
POST /v1/tenants/{tenantId}/api-keys
For example when a tenant lost its last admin key. The secret is shown once.
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId |
Request body: ApiKeyCreate
| Status | Meaning | Body |
|---|---|---|
| 201 | Key created. | ApiKeyCreated |
| 400 | The request is malformed or a value is out of range. Code validation_failed. |
Problem |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
Revoke a tenant's API key
DELETE /v1/tenants/{tenantId}/api-keys/{keyId}
| Parameter | In | Type | Description |
|---|---|---|---|
tenantId (required) |
path | TenantId | |
keyId (required) |
path | string |
| Status | Meaning | Body |
|---|---|---|
| 204 | Key revoked. | |
| 401 | Missing, unknown or revoked API key. Code unauthorized. |
Problem |
| 403 | The key lacks the scope, the queue is outside its patterns, or a tenant key called an operator endpoint: code forbidden. The key's tenant is suspended: code tenant_suspended. |
Problem |
| 404 | No such queue or message for this tenant. Code not_found. |
Problem |
System
Liveness, no authentication.
Liveness and database reachability
GET /healthz
| Status | Meaning | Body |
|---|---|---|
| 200 | The server and its database are reachable. | object |
| 503 | The database or Redis is unreachable. | Problem |
Schemas
QueueName
Type: string
Route
The path a worker runs its jobs through: a VPN exit, a proxy, an API account, a
region. The server records the route of every attempt; with the queue's
route_policy set to avoid_failed, a message is not handed to a worker on a
route where it failed within the cooldown.
Type: string (up to 255 characters)
MessageStatus
pending: waiting for a worker (ready, or delayed until available_at).
processing: leased to a worker.
completed: acked.
failed: out of attempts, or permanently failed; this is the dead-letter set.
Type: string: pending, processing, completed, failed
Headers
Free string metadata, passed through untouched (for example a message type for a framework).
Type: map of string
PublishRequest
| Field | Type | Description |
|---|---|---|
body (required) |
any JSON value | Any JSON value. Passed to the worker exactly as given. |
headers |
Headers | |
dedup_key |
string (up to 255 characters) | While a message with this key is open in this queue, publishing again returns that message. |
delay_seconds |
integer (min 0) | Make the message available this many seconds from now. Not together with available_at. |
available_at |
string (date-time) | Make the message available at this time. Not together with delay_seconds. |
max_attempts |
integer (min 1) | Overrides the queue's max_attempts for this message, capped at the queue's max_attempts_limit. |
PublishResponse
| Field | Type | Description |
|---|---|---|
id (required) |
string | |
queue (required) |
QueueName | |
status (required) |
MessageStatus | |
created_at (required) |
string (date-time) | |
available_at (required) |
string (date-time) | |
duplicate (required) |
boolean | True when an open message with the same dedup_key was returned instead of a new one. |
ClaimRequest
| Field | Type | Description |
|---|---|---|
consumer |
string (up to 255 characters) | Free identifier of the worker (hostname, pod name), shown in the dashboard. Not used for authorisation. |
route |
Route | |
wait_seconds |
integer (min 0, max 20) | Wait up to this long for a message instead of returning 204 at once. Default: 0. |
lease_seconds |
integer (min 1) | Lease length for this claim, capped at the queue's max_lease_seconds. Defaults to the queue's lease_seconds. |
DeliveredMessage
| Field | Type | Description |
|---|---|---|
id (required) |
string | |
queue (required) |
QueueName | |
body (required) |
any JSON value | The JSON value given at publish. |
headers (required) |
Headers | |
attempt (required) |
integer (min 1) | Which attempt this is, counting this one. |
max_attempts (required) |
integer (min 1) | |
created_at (required) |
string (date-time) |
Lease
| Field | Type | Description |
|---|---|---|
receipt (required) |
string | Proof of this lease. Required to extend, ack, fail or release. Opaque; a new one per claim. |
lease_until (required) |
string (date-time) | The lease ends here unless it is extended. |
message (required) |
DeliveredMessage |
ReceiptRequest
| Field | Type | Description |
|---|---|---|
receipt (required) |
string |
ExtendRequest
| Field | Type | Description |
|---|---|---|
receipt (required) |
string | |
lease_seconds |
integer (min 1) | New lease length from now, capped at the queue's max_lease_seconds. |
ExtendResponse
| Field | Type | Description |
|---|---|---|
lease_until (required) |
string (date-time) |
ErrorReport
| Field | Type | Description |
|---|---|---|
type |
string (up to 255 characters) | Machine-readable kind of error, typically the exception class. Used to filter the dead-letter set. |
message (required) |
string (up to 65535 characters) | |
details |
any JSON value | Any JSON value with more context (stack trace, response code). Stored, not interpreted. |
FailRequest
| Field | Type | Description |
|---|---|---|
receipt (required) |
string | |
error (required) |
ErrorReport | |
permanent |
boolean | The input itself cannot be processed. A fact for the server, which decides what it means via on_permanent. Default: false. |
FailResponse
| Field | Type | Description |
|---|---|---|
outcome (required) |
string: retrying, dead_lettered, discarded |
What the server did. retrying: pending again from available_at. dead_lettered: status failed. discarded: deleted (queue setting on_exhausted: discard). |
available_at |
string or null (date-time) | |
attempt (required) |
integer | |
max_attempts (required) |
integer |
ReleaseRequest
| Field | Type | Description |
|---|---|---|
receipt (required) |
string | |
delay_seconds |
integer (min 0) | Default: 0. |
Message
The full message, as an administrator sees it.
| Field | Type | Description |
|---|---|---|
id (required) |
string | |
queue (required) |
QueueName | |
status (required) |
MessageStatus | |
body (required) |
any JSON value | The JSON value given at publish. |
headers (required) |
Headers | |
dedup_key |
string or null | |
attempts (required) |
integer (min 0) | Attempts started so far; an expired lease counts, a release does not. |
max_attempts (required) |
integer | |
available_at (required) |
string (date-time) | |
lease_until |
string or null (date-time) | |
consumer |
string or null | The consumer of the current or last claim. |
last_error |
RecordedError or null | |
failed_routes |
map of string (date-time) | Route to the time an attempt last failed on it. |
created_at (required) |
string (date-time) | |
updated_at (required) |
string (date-time) | |
completed_at |
string or null (date-time) | |
failed_at |
string or null (date-time) |
RecordedError
All fields of ErrorReport, and:
| Field | Type | Description |
|---|---|---|
at (required) |
string (date-time) | |
attempt (required) |
integer | |
permanent (required) |
boolean | |
expired |
boolean | True when the attempt ended because the lease expired, not by a fail call. |
route |
string or null | |
consumer |
string or null |
MessagePage
| Field | Type | Description |
|---|---|---|
items (required) |
array of Message | |
next_cursor (required) |
string or null |
Backoff
Delay before attempt n+1 after attempt n failed: min(initial_seconds * multiplier^(n-1), max_seconds), then randomised by +/- jitter.
| Field | Type | Description |
|---|---|---|
initial_seconds |
integer (min 0) | Default: 10. |
multiplier |
number (min 1) | Default: 2. |
max_seconds |
integer (min 0) | Default: 3600. |
jitter |
number (min 0, max 1) | Default: 0.1. |
RoutePolicy
| Field | Type | Description |
|---|---|---|
mode |
string: none, avoid_failed |
avoid_failed: do not hand a message to a worker on a route where it failed within cooldown_seconds. Default: "none". |
cooldown_seconds |
integer (min 0) | How long a failed route stays excluded for that message. When it runs out, the route may be tried again, so a message that failed on every route still makes progress and max_attempts ends it. Default: 3600. |
Retention
| Field | Type | Description |
|---|---|---|
completed_seconds |
integer (min 0) | Default: 86400. |
failed_seconds |
integer (min 0) | Default: 604800. |
QueueSettings
| Field | Type | Description |
|---|---|---|
lease_seconds (required) |
integer (min 1) | Default: 300. |
max_lease_seconds (required) |
integer (min 1) | Upper bound for one claim or one extend. A job may run longer as long as its worker keeps extending. Default: 3600. |
max_attempts (required) |
integer (min 1) | Default: 7. |
max_attempts_limit (required) |
integer (min 1) | Highest max_attempts a publisher may ask for. Default: 25. |
backoff (required) |
Backoff | |
on_exhausted (required) |
string: dead_letter, discard |
What happens after the last attempt fails. Default: "dead_letter". |
on_permanent (required) |
string: dead_letter, retry |
What a fail with permanent: true does. retry treats it like any other failure. Default: "dead_letter". |
route_policy (required) |
RoutePolicy | |
retention (required) |
Retention | |
max_message_bytes (required) |
integer (min 1) | Upper bound for the encoded body plus headers. Default: 1048576. |
paused (required) |
boolean | Default: false. |
QueueSettingsPatch
Any subset of the queue settings; nested objects are merged.
| Field | Type | Description |
|---|---|---|
lease_seconds |
integer (min 1) | |
max_lease_seconds |
integer (min 1) | |
max_attempts |
integer (min 1) | |
max_attempts_limit |
integer (min 1) | |
backoff |
Backoff | |
on_exhausted |
string: dead_letter, discard |
|
on_permanent |
string: dead_letter, retry |
|
route_policy |
RoutePolicy | |
retention |
Retention | |
max_message_bytes |
integer (min 1) | |
paused |
boolean |
QueueStats
| Field | Type | Description |
|---|---|---|
ready (required) |
integer | Pending and available now. |
delayed (required) |
integer | Pending, available later (backoff or delay). |
processing (required) |
integer | |
completed (required) |
integer | Completed and not yet removed by retention. |
failed (required) |
integer | The dead-letter set. |
oldest_ready_seconds (required) |
integer | How long the oldest ready message has been waiting. Grows when no worker takes the queue. |
oldest_processing_seconds (required) |
integer |
Queue
| Field | Type | Description |
|---|---|---|
name (required) |
QueueName | |
settings (required) |
QueueSettings | |
stats (required) |
QueueStats | |
paused_at |
string or null (date-time) |
BulkFilter
| Field | Type | Description |
|---|---|---|
status (required) |
string: completed, failed |
|
error_type |
string | Only messages whose last error has this type. |
before |
string (date-time) | Only messages that reached their status before this time. |
limit |
integer (min 1, max 10000) | Default: 1000. |
BulkResult
| Field | Type | Description |
|---|---|---|
count (required) |
integer |
Scope
Type: string: publish, consume, admin
ApiKey
| Field | Type | Description |
|---|---|---|
id (required) |
string | |
name (required) |
string | |
prefix (required) |
string | The first characters of the secret, to recognise a key in logs and lists. |
scopes (required) |
array of Scope | |
queues (required) |
array of string | Glob patterns of queue names the key may use. Empty means all queues. |
created_at (required) |
string (date-time) | |
last_used_at |
string or null (date-time) |
ApiKeyCreate
| Field | Type | Description |
|---|---|---|
name (required) |
string (up to 255 characters) | |
scopes (required) |
array of Scope | |
queues |
array of string | Default: []. |
ApiKeyCreated
All fields of ApiKey, and:
| Field | Type | Description |
|---|---|---|
secret (required) |
string | The API key. Shown once. |
TenantId
Short, stable identifier, chosen at creation. Used in the LessorMQ-Tenant header and in metrics.
Type: string
TenantStatus
Type: string: active, suspended, deleting
Quotas
Limits per tenant. null means unlimited. Exceeding a rate returns 429 rate_limited.
| Field | Type | Description |
|---|---|---|
max_queues |
integer or null (min 1) | |
max_open_messages |
integer or null (min 1) | Pending plus processing, across all queues. Publishing beyond it returns 429. |
publish_per_second |
integer or null (min 1) | |
claim_per_second |
integer or null (min 1) | |
max_message_bytes |
integer or null (min 1) | Upper bound for every queue's max_message_bytes in this tenant. |
max_retention_seconds |
integer or null (min 0) | Upper bound for every queue's retention in this tenant. |
TenantUsage
| Field | Type | Description |
|---|---|---|
queues (required) |
integer | |
open_messages (required) |
integer | |
failed_messages (required) |
integer |
Tenant
| Field | Type | Description |
|---|---|---|
id (required) |
TenantId | |
name (required) |
string | |
status (required) |
TenantStatus | |
quotas (required) |
Quotas | |
queue_defaults (required) |
QueueSettings | |
usage (required) |
TenantUsage | |
created_at (required) |
string (date-time) | |
suspended_at |
string or null (date-time) |
TenantCreate
| Field | Type | Description |
|---|---|---|
id |
TenantId | |
name (required) |
string (up to 255 characters) | |
quotas |
Quotas | |
queue_defaults |
QueueSettingsPatch | |
create_admin_key |
boolean | Also create a first key with all three scopes and return it once. Default: true. |
TenantCreated
All fields of Tenant, and:
| Field | Type | Description |
|---|---|---|
admin_key |
ApiKeyCreated or null |
TenantPatch
Only the fields present change. id cannot change. deleting is set by
deleteTenant, never here.
| Field | Type | Description |
|---|---|---|
name |
string (up to 255 characters) | |
status |
string: active, suspended |
|
quotas |
Quotas | |
queue_defaults |
QueueSettingsPatch |
Problem
RFC 9457 problem details, with a stable code to branch on.
| Field | Type | Description |
|---|---|---|
type (required) |
string (uri) | urn:lessormq:problem:<code>. |
title (required) |
string | |
status (required) |
integer | |
detail |
string | |
code (required) |
string: validation_failed, unauthorized, forbidden, tenant_suspended, not_found, lease_lost, invalid_state, payload_too_large, rate_limited, unavailable, internal |
|
errors |
array of object | Per-field problems, for validation_failed. |