Work queues (mailboxes)

All paths are relative to the API base URL (https://api.getrunstate.com) and require Authorization: Bearer <api key>. See the API overview for authentication, idempotency and the error envelope.

GET /mailboxes

GET /v1/spaces/{spaceId}/mailboxes

Read-only mailbox list for consoles.

• Key permission: coordination_read

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required

Responses

Status	Meaning
200	Mailboxes

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /mailboxes

POST /v1/spaces/{spaceId}/mailboxes

Create work mailbox or inbox.

• Key permission: resource_config
• Idempotency-Key header: required

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
name	string	yes
mode	string	no	one of WORK, INBOX; default "WORK"
recipientId	string	no
backlogLimit	integer	no	default 1000
maxAttempts	integer	no	1–100; default 5; Deliveries allowed before the task fails (nacks and lapsed leases both count)

Responses

Status	Meaning
201	Created

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

GET /mailboxes/{id}/messages

GET /v1/spaces/{spaceId}/mailboxes/{id}/messages

Read-only message list with optional state filter.

• Key permission: coordination_read

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Responses

Status	Meaning
200	Messages

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/messages" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /mailboxes/{id}/messages

POST /v1/spaces/{spaceId}/mailboxes/{id}/messages

Send scoped message (work_key dedup applies)

• Key permission: coordination_write
• Idempotency-Key header: required

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
scopeId	string (uuid)	yes
payload	any JSON	yes
workKey	string	no
deadline	string (date-time)	no

Responses

Status	Meaning
200	Dedup replay of committed send
201	Message id
409	Error envelope {"error":{"code","message","requestId"}}

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/messages" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","payload":{"example":true}}'

POST /mailboxes/{id}/recv

POST /v1/spaces/{spaceId}/mailboxes/{id}/recv

Receive-and-claim next ready message for a scope.

• Key permission: coordination_write

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
scopeId	string (uuid)	yes
holder	string	yes
holderSession	string	yes
leaseSeconds	integer	no	default 30
waitMs	integer	no	0–120000; Long-poll an empty receive for up to this many milliseconds (capped by the server at api.longPollMaxWaitMs; 0 or absent answers at once). Returns as soon as work is available, when the wait ends, or when the API starts draining. An empty long poll of at least 1000 ms does not count toward request rate limits.

Responses

Status	Meaning
200	Message with claim token
204	No ready message (after the waitMs long poll
409	Error envelope {"error":{"code","message","requestId"}}

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/recv" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","holder":"worker-1","holderSession":"<session id>"}'

POST /messages/{id}/renew

POST /v1/spaces/{spaceId}/messages/{id}/renew

Renew current receive claim; also extends pool grants admitted with this delivery.

• Key permission: coordination_write
• TypeScript SDK: runstate.serve() (automatic while a handler runs)
• Python SDK: runstate.serve() (automatic while a handler runs)

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
token	string	yes
leaseSeconds	integer	no	5–600; default 30

Responses

Status	Meaning
200	Renewed
409	Error envelope {"error":{"code","message","requestId"}}

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/renew" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'

POST /messages/{id}/complete

POST /v1/spaces/{spaceId}/messages/{id}/complete

Ack plus optional result atomically.

• Key permission: coordination_write
• TypeScript SDK: runstate.serve() (handler returned)
• Python SDK: runstate.serve() (handler returned)

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
token	string	yes
result	object	no	Optional. payload alone records the task outcome without publishing a result message; mailboxId and scopeId must be sent together to also publish the result to that mailbox.
result.mailboxId	string (uuid)	no
result.scopeId	string (uuid)	no
result.payload	any JSON	no
result.workKey	string	no

Responses

Status	Meaning
200	ACKED
409	Error envelope {"error":{"code","message","requestId"}}

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/complete" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'

POST /messages/{id}/nack

POST /v1/spaces/{spaceId}/messages/{id}/nack

Retry or reject current claim.

• Key permission: coordination_write
• TypeScript SDK: runstate.serve() (handler threw)
• Python SDK: runstate.serve() (handler raised)

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
id	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
token	string	yes
retry	boolean	yes
error	string	no	max length 2000; The handler’s error; kept as the task’s outcome reason when this is the last attempt

Responses

Status	Meaning
200	New message state
409	Error envelope {"error":{"code","message","requestId"}}

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/nack" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>","retry":true}'

PUT /mailboxes/by-name/{name}

PUT /v1/spaces/{spaceId}/mailboxes/by-name/{name}

Look up a queue by name, or create-or-verify it when any setting is given.

Creating a missing queue also needs resource_config.

• Key permission: coordination_read
• TypeScript SDK: runstate.queue(name)
• Python SDK: runstate.queue(name)

Path parameters

Name	Type	Notes
spaceId	string (uuid)	required
name	string	length 1–256

Request body (JSON)

Field	Type	Required	Notes
mode	string	no	one of WORK, INBOX
backlogLimit	integer	no	1–100000
maxAttempts	integer	no	1–100
requirements	object	no
requirements.pools	array of object	no
requirements.pools[].name	string	yes
requirements.pools[].units	integer	yes	min 1
requirements.quotas	array of object	no
requirements.quotas[].name	string	yes
requirements.quotas[].units	integer	yes	min 1
requirements.budgets	array of object	no
requirements.budgets[].name	string	yes
requirements.budgets[].reserveMinor	string	yes	pattern ^\d+$

Responses

Status	Meaning
200	Existing queue
201	Created
404	Error envelope {"error":{"code","message","requestId"}}
409	Error envelope {"error":{"code","message","requestId"}}

curl -X PUT "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/by-name/<name>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'