Quickstart

Last updated Sep 23, 2026

Spooler is a managed message queue with a small surface. Send bytes, receive them in a worker, and acknowledge the work once it is done. Receiving leases a message; it does not delete it. Use it for background jobs, webhook delivery, and work shared by a pool of workers — work that must survive a crash and needs retries when a worker fails.

You need curl and an API key from the console. Without an account, the local image runs the same API in memory — any key is accepted:

docker run --rm -p 127.0.0.1:8080:8080 spoolersh/memspoold

export SPOOLER_KEY='<your api key>'
export SPOOLER_API=https://api.spooler.sh/v1   # local: http://localhost:8080/v1

Every account has a spool named default. The queues in these examples live there.

Create a queue

curl -X PUT "$SPOOLER_API/spools/default/queues/test" \
  -H "Authorization: Bearer $SPOOLER_KEY"

Returns 201, with the server's default settings.

Send a message

curl -si -X POST "$SPOOLER_API/spools/default/queues/test/send" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  --data-binary 'hello, world'

HTTP/2 201
spooler-message-id: 1-1

The body you send is the message — bytes in, bytes out, no envelope; the new message's id comes back as a header. On the hosted service 201 means the message is stored: written and synced to disk, and confirmed by the copies the spool's replication requires, before the response. The local image keeps it in memory.

Receive it

curl -si -X POST "$SPOOLER_API/spools/default/queues/test/recv?waitSeconds=20" \
  -H "Authorization: Bearer $SPOOLER_KEY"

HTTP/2 200
spooler-lease: dGhpcyBpcyBub3QgYSByZWFsIGxlYXNl
spooler-message-id: 1-1
spooler-message-retries: 0
spooler-lease-expires-at: 2026-08-12T10:00:30Z

hello, world

waitSeconds=20 long-polls: the call waits until a message becomes visible or the wait elapses (204). Omitting it waits the same maximum; waitSeconds=0 returns immediately.

Receiving does not delete the message — it leases it. While the lease is live, no other receiver gets the message; if you never settle it, the lease times out and the message is redelivered.

Acknowledge it

curl -X POST "$SPOOLER_API/spools/default/ack" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Lease: <the spooler-lease header value>"

Returns 204. The message is acknowledged and removed from the queue. That is the whole loop: send, receive, ack.

Where to go next

• What a delivery guarantees, and what it doesn't — Delivery.
• Give up on a delivery instead of acking it — nack returns it for redelivery; after the queue's maxRetries it is failed, where a listing finds it.
• A pipeline stage acks its input and sends the next message in one atomic call — ack-and-send.
• Tune a queue — lease timeout, retries, retention, dedup window — with Update queue settings; read the applied settings back with List queues.
• Retry sends safely with deduplication.
• What the server enforces: limits and errors.
• Every operation, generated from the spec — API reference.
• Run it locally for development and tests — Running locally.
• What Spooler deliberately is not — non-goals and alternatives.