API reference

Last updated Aug 20, 2026

Every operation has its own page in the sidebar. This page is what is true of all of them.

Endpoint

Every path below is relative to the base URL:

https://api.spooler.sh/v1

The spoolersh/memspoold image serves the same API on http://localhost:8080/v1.

Authentication

Every operation authenticates with an API key from the console, presented as a bearer token:

Authorization: Bearer <key>

A missing or bad key fails with 401; a suspended account with 402. Keys never travel in query strings.

Addressing

Every operation names one of your spools: /spools/{spool}/… (the quickstart uses default). Queue operations address /queues/{queue} under it. Ack, nack, renew, recover, and discard are spool-scoped — the lease already names the queue, so a wrong queue is unrepresentable. Name rules are in limits.

Bodies

A send's request body is the payload — raw application/octet-stream, Content-Length required (411 without it). A receive's or peek's response body is the payload; message attributes ride Spooler-* response headers. Everything else is JSON in, JSON out. There is no envelope and no base64.

Spooler-* headers

Message attributes travel as Spooler-* headers. Each operation accepts only the headers it defines: any other fails with 400 kind unknown_header — a typo is refused, never silently ignored.

Header	Direction	Operations
Spooler-Dedup-Hash	request	Send a message
Spooler-Dedup-String	request	Send a message
Spooler-Delay	request	Send a message
Spooler-Lease	response	Receive a message, Peek the oldest failed message
Spooler-Lease-Expires-At	response	Receive a message
Spooler-Message-Id	response	Receive a message, Peek the oldest failed message
Spooler-Retry-Count	response	Receive a message, Peek the oldest failed message

Durations are Go duration strings (500ms, 5s, 1m30s, 168h); timestamps are RFC 3339 UTC.

Responses

200 carries a body; 201 means created or durably appended; 204 means done with nothing to say (an ack, a delete, an empty receive). Errors are JSON {"error", "kind"} — match on the status and kind, see errors. 429 carries Retry-After (see limits); 503 means the spool is momentarily unavailable — retry.

Operations

All 13 operations:

Queues

PUT /spools/{spool}/queues/{queue}	Create a queue
PATCH /spools/{spool}/queues/{queue}	Update queue settings
DELETE /spools/{spool}/queues/{queue}	Delete a queue
GET /spools/{spool}/queues	List queues
GET /spools/{spool}/stats	Get spool stats

Messages

POST /spools/{spool}/queues/{queue}/send	Send a message
POST /spools/{spool}/queues/{queue}/recv	Receive a message
POST /spools/{spool}/ack	Acknowledge a processed message
POST /spools/{spool}/nack	Requeue a message for retry
POST /spools/{spool}/renew	Renew a lease
POST /spools/{spool}/discard	Discard a message

Failure queue

GET /spools/{spool}/queues/{queue}/failures/head	Peek the oldest failed message
POST /spools/{spool}/recover	Recover a failed message