HTTP API conventions

Queen’s broker speaks plain HTTP/1.1 with JSON bodies. There is no binary protocol, no persistent session, and no client-side coordination state. Anything that can issue an HTTP request is a first-class client. The rules on this page hold for every route; the per-route pages only document what is specific to that route.

Base URL and versioning

The broker binds PORT, which defaults to 6632, on QUEEN_BIND_ADDR, which defaults to 0.0.0.0. A local broker is therefore at http://localhost:6632.

There is exactly one API version, v1. Since the 1.0.0 line, broker and SDK minor versions are released in alignment. A path is the API version: there is no Accept header negotiation and no version query parameter.

Anything the router does not match falls through to the dashboard. That fallback answers a JSON 404 ({"error":"Not Found","code":"no_such_route"}) for any path starting with /api/ and for any non-GET/HEAD request, so a call to a route that does not exist fails loudly instead of returning the SPA’s HTML with a 200.

Authentication

JWT bearer authentication is off by default (JWT_ENABLED=false); with it off, every route is reachable unauthenticated and the broker relies entirely on network isolation. With it on, send the token in the standard header:

Authorization: Bearer <jwt>

A bare token with no Bearer prefix is also accepted. Supported algorithms are HS256/384/512, RS256/384/512 and EdDSA, selected by JWT_ALGORITHM (or auto); the verification key comes from a static PEM or from a JWKS endpoint cached per kid. Role claim names are remappable. The configuration page lists every JWT_* variable, and Self-hosting covers key distribution.

Two failure codes, and they mean different things:

Access levels are a role set, not a ladder

Every route is mapped to one of five access levels. The mapping from a token’s roles to the levels it satisfies is not hierarchical: write-only is not a weaker read-write, it is a different capability. This matters most for producers.

Three routes are write-only, and all three are pure produce operations: POST /api/v1/push, POST /api/v1/timers (scheduling a timer produces the message it becomes) and POST /api/v1/ephemeral/push. So a token whose single role is write-only can produce and can do nothing else: every read route and every consume route (/pop, /ack, /transaction, /lease/:leaseId/extend) is read-write and returns 403 for it. Conversely a read-only token cannot pop, because popping takes a lease and mutates a cursor.

Role names come from the role claim and the roles array claim, and both the claim names and the four role names are configurable. A path the access table does not recognise defaults to read-write.

The public routes, reachable with no token even when authentication is on, are /health, /metrics, /metrics/prometheus, /, /assets/*, /favicon*, and the three dashboard-identity routes /auth/me, /auth/login and /auth/logout. The last three are public so they can answer the auth question themselves: with JWT on, /auth/me returns 401 from its own handler and /auth/login serves the page that says the dashboard needs the proxy. /metrics/prometheus being public is deliberate for scraping and is a hazard in a multi-tenant deployment, where per-queue series sum across tenants; see Self-hosting.

A second, independent exemption list is JWT_SKIP_PATHS, which defaults to /health,/metrics/prometheus,/metrics,/. Entries match a path exactly, or as a prefix when the entry ends in /. A path on that list skips authentication entirely, so widening it widens the unauthenticated surface.

Requests

Bodies are JSON. The broker reads the raw bytes and parses them as JSON without inspecting Content-Type, so sending application/json is good manners rather than a requirement. A body that does not parse returns 400 with the parser’s message:

{"error":"bad body: expected value at line 1 column 1"}

Query parameters on the message-plane routes are typed, not free-form strings: batch=abc is a deserialization failure for the whole query string rather than a silently-ignored parameter, and it is rejected by the extractor before the handler runs. Management routes that take filter parameters read them as strings and additionally accept 1/0 and yes/no for booleans.

The request body cap is 64 MiB (QUEEN_MAX_BODY_BYTES, default 67108864). A larger body is rejected by the body-limit layer before any handler runs. The cap applies per request, so a push of many small messages is bounded by the sum of their payloads plus JSON framing.

Responses

Successful API responses carry Content-Type: application/json. The exception is /metrics/prometheus, which returns text/plain; version=0.0.4; charset=utf-8 with Cache-Control: no-cache.

Every 204 has no body at all

When a pop has nothing to deliver, the broker returns 204 No Content with no body and no Content-Length. This is deliberate, and it is not cosmetic: announcing a content length for a body that hyper then elides makes strict HTTP/1.1 clients (Node’s undici/llhttp in particular) treat the connection as poisoned and close it, which under empty-poll load snowballs into ECONNRESET storms. The bodies that were dropped carried nothing a client read.

Consequences you have to design around:

• Check the status code before parsing. A 204 has no JSON to parse.
• Any diagnostic the handler wanted to attach to an empty result is lost. Pop maintenance mode is the clearest case: the handler builds {"messages":[],"paused":true}, and the client sees a bare 204 indistinguishable from an empty queue.
• An error reported inside a pop stored procedure’s result also renders as an empty pop, and therefore as a 204 with no text. Genuine transport-level failures (no pool connection, a statement timeout) come back as 500 with a body.

Errors

Every error the broker produces itself is a flat object with one key:

{"error":"invalid or expired lease"}

The message is JSON-escaped, so it is always parseable. There is no error code enum, no details object and no retryAfter; the HTTP status plus this string is the whole contract.

Some routes return a stored procedure’s JSON verbatim

Queen’s management surface is implemented in PostgreSQL. Many routes (/api/v1/configure and most of the resources, status, analytics, consumer-groups, messages, dlq and traces handlers) pass the stored procedure’s JSON straight through without reshaping it, because clients assert on those exact keys. Two things follow:

• The shape of those responses is the stored procedure’s shape, including keys that only make sense internally.
• When such a result carries an error key, the broker maps it to a status code by inspecting the text: 404 if the message contains not found (case-insensitive), otherwise 500. The original body is preserved.

The message-plane routes on the following pages are the opposite: their bodies are assembled by hand in the broker, field by field, and the fields that are absent are as load-bearing as the ones that are present.

A 2xx does not mean every item succeeded

/api/v1/push, /api/v1/ack and /api/v1/ack/batch answer with a top-level JSON array, one element per request item, in request order. The HTTP status describes the call; each element describes one item.

A client that only checks res.ok will silently lose messages: a push whose database transaction failed still returns 201, with the affected items marked buffered (spooled to disk for replay) or failed (not stored anywhere).

Status codes used by the message plane

On the message plane the broker never returns 429: it has no per-client rate limiter there. Its internal admission arbiter is adaptive and makes a request wait for a slot rather than rejecting it, and rate limiting on those routes comes from the multi-tenant gateway rather than from the broker.

The kv, timer and ephemeral routes are the exception, and they are the exception on purpose. They are the surfaces whose call rate is decided by an end user of the customer rather than by a volume of messages, so a defence that lived only in the gateway would not be a defence of the product: self-hosted and dedicated deployments without a gateway are real. Those routes carry a per-tenant token bucket in the broker itself and answer 429 with Retry-After. They also answer 403 and 503 where the message plane has no equivalent, and their pages carry the one sentence that separates the three.

Retrying safely

The KV operations differ from each other, which is the part that catches people out.

The exception under incr is worth stating exactly, because it is the case that makes a counter wrong rather than an operation fail: a retry counts twice unless the transaction that carried it failed. Inside POST /api/v1/transaction a rolled-back bundle wrote nothing, so re-sending it is safe; standalone on POST /api/v1/kv, a timeout leaves you unable to tell whether the increment committed, and there is no expect to make the second attempt conditional. Either put the incr in a transaction whose failure you can observe, or accept that a retry may double it.

The tenant-scoped column

The generated route table has a Tenant-scoped column. It records whether that handler resolves a tenant identity for the request and threads it into the SQL that resolves queues by name. Native tenant scoping is off by default; with it off, every request resolves to a single default tenant and the column tells you which handlers would participate if it were on. It is an operator-level feature of multi-tenant deployments, not a client-facing one. Self-hosting and Internals cover it, including which routes are not scoped and what that implies.

Every route

Queen’s broker registers 93 method + path pairs. Every row below is read out of the router and the authorization table at build time.

Message plane

Queues and partitions

Consumer groups

Messages, DLQ and traces

Status, metrics and analytics

Streams

Key/value state and timers

Ephemeral queues

Operator surfaces

Dashboard identity (broker-direct)

Internal (broker-to-broker)

Ungrouped

69 of these handlers resolve a tenant from the request; 15 /api/v1/* routes do not and are therefore cell-wide reads or operator surfaces.