Renew a lease

Last updated Aug 20, 2026

POST /spools/{spool}/renew

Resets the lease expiry to now plus the lease's queue's current lease timeout — a reset, not an extension: after a settings update the new expiry can land earlier than the previous one. On a queue with no lease timeout this is a no-op and expiresAt is omitted (the lease never expires).

Sample

curl -X POST "$SPOOLER_API/spools/<spool>/renew" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Content-Type: application/json" \
  --data '{"lease": "<lease>"}'

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.

Request body

Required; application/json.

Field	Type	Required	Description
lease	LeaseToken, 16–128 chars, ^[A-Za-z0-9_-]+$	yes	Opaque signed lease token (base64url) from a receive or from failures/head. Scoped to the operations of its source: a receive lease settles (ack/nack/renew), a failure lease recovers or discards — never interchangeable. Never inspect or construct one.

Responses

Status	Description
200	Renewed.
400	The request is malformed; the kind names the problem.
401	The API key is missing or not recognized.
402	The account is suspended.
403	A plan limit refuses the operation; the kind names it.
404	The spool or queue does not exist; the kind says which.
409	Concurrent state refuses the operation; the kind names it.
410	The lease no longer settles anything: expired, already settled, or predates a primary change.
429	The per-account request rate cap is exceeded; retry after the Retry-After delay.
503	The spool is momentarily unavailable.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted.