Create a queue

Last updated Aug 20, 2026

PUT /spools/{spool}/queues/{queue}

Creates the queue on the spool. Queue names are unique within the spool; the name is immutable after creation, the settings can be changed with updateQueue. Creating an existing queue fails with 409 regardless of settings.

Sample

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

Parameters

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

Request body

Optional; application/json.

Field	Type	Required	Description
leaseTimeoutSeconds	integer, 0–31,536,000, default 300	no	Seconds to wait before an unacked delivery is auto-nacked; 0 disables the timeout, at most a year. The server default applies when omitted.
maxRetries	integer, 0–65,535, default 10	no	Redeliveries before a message lands in the failure queue; 0 means no retries. The server default applies when omitted.
dedupWindowSeconds	integer, 0–300	no	Seconds a dedup key is remembered for deduplication, at most five minutes. Omitted or 0 disables dedup.
retentionSeconds	integer, ≥ 60	no	Seconds a message is kept before it is discarded; at least a minute, at most the plan's retention limit. Omitted means the server default, clamped to the plan's limit.
effectiveRetentionSeconds	integer, ≥ 0	no	The retention actually enforced: retentionSeconds bounded by the plan's retention limit. Response-only; ignored in requests.
recvRateLimit	RateLimit	no	Caps the rate Recv hands out messages; absent means no limit.

Responses

Status	Description
201	Created.
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.
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.