Create a queue

Last updated Oct 2, 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"

Parameters

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

Request body

Optional; application/json.

The shape, not a sample: values are the wire types; ? marks an optional field.

{
  // Seconds to wait before an unacked delivery is auto-nacked; 0 disables
  // the timeout, at most a year. The server default applies when omitted.
  //
  // Range:   0–31,536,000
  // Default: 300
  leaseTimeoutSeconds?: integer,

  // Redeliveries before a message is failed; 0 means no retries. The
  // server default applies when omitted.
  //
  // Range:   0–65,535
  // Default: 10
  maxRetries?: integer,

  // Seconds a dedup key is remembered for deduplication, at most five
  // minutes. Omitted or 0 disables dedup.
  //
  // Range: 0–300
  dedupWindowSeconds?: integer,

  // Seconds a message is kept before it is discarded, counted as
  // effectiveRetentionSeconds describes; at least a minute, at most the
  // plan's retention limit. Omitted means the server default, clamped to
  // the plan's limit.
  //
  // Range: ≥ 60
  retentionSeconds?: integer,

  // Caps the rate Recv hands out messages; absent means no limit.
  recvRateLimit?: {
    // The token-bucket refill interval in microseconds — one sustained
    // message per interval, so 10000 (the minimum, 10ms) is 100/s. Burst
    // is idle catch-up only; it does not raise the sustained rate.
    //
    // Range: ≥ 10,000
    intervalMicros: integer,

    // The bucket size: how many messages an idle queue may release at
    // once before the sustained rate takes over.
    //
    // Range: 1–2,147,483,647
    burst: integer,
  },
}

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. A 403 without a kind, on any operation, means the API key is blocked.
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. The body names the kind (rate_limited); the wait is the Retry-After header and is not repeated in the body. Headers are as structured as the body, and this one is the header HTTP defines for a wait.
503	The spool is momentarily unavailable.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted, whole and at least 1; always the delay-seconds form, never an HTTP-date.