Delete a queue

Last updated Aug 20, 2026

DELETE /spools/{spool}/queues/{queue}

Deletes the queue. In force mode the queue and every message in it are deleted right away; the call returns once the deletion is durable and the name is free for reuse. In drain mode the queue stops accepting new messages, remains consumable until the backlog is drained, and is then deleted; the call returns 202 as soon as the drain intent is durable. Deletion survives restarts either way. The mode is required: deleting a non-empty queue is destructive in force mode, so the choice is always explicit.

Sample

curl -X DELETE "$SPOOLER_API/spools/<spool>/queues/<queue>?mode=<mode>" \
  -H "Authorization: Bearer $SPOOLER_KEY"

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.
mode	query	force / drain	yes	force deletes the queue and every message in it right away; drain refuses new messages, lets consumers empty the backlog, and deletes the queue when it is drained.

Responses

Status	Description
202	Deletion is durable and in progress: the drain was accepted, or an immediate deletion did not finish within the request window. The queue refuses the affected operations already; the name frees up when the deletion completes.
204	Deleted; the name is free for reuse.
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	A concurrent queue update lost the race; retry.
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.