Every QueenMQ node serves the whole API over plain HTTP with JSON bodies, on port 6632. There is no
second protocol to learn and no admin port: curl is a complete client, and every SDK is a thin
layer over the routes on this page. We kept it that way on purpose, so that when something looks
wrong you can ask the broker directly, with the tools already on your machine.
The page starts with what every route shares, then lists every route the broker registers, then documents message browsing, reads by offset, and the control-plane API the embedded proxy adds.
Base URL
curl -s http://localhost:6632/health| Setting | Default | Effect |
|---|---|---|
PORT |
6632 |
The HTTP port. |
QUEEN_BIND_ADDR |
0.0.0.0 |
The address the listener binds. |
QUEEN_MAX_BODY_BYTES |
67108864 (64 MiB) |
A larger request body is refused with 413 before it is parsed. This 413 is plain text, not the JSON {error, code} body. |
The broker’s own listener is plain HTTP. TLS is served by the proxy built into the same binary
(QUEEN_PROXY_EMBEDDED=true), from QUEEN_TLS_CERT and QUEEN_TLS_KEY, two PEM file paths that
are set together or not at all. See security.
Which node to call
Any node of a cluster answers any request. By default (QUEEN_RAFT_CLIENT_OFFLOAD, on) every node
serves its own clients: it parses and validates the request, prepares the command exactly as the
leader would, sends the leader only that prepared command, and answers from its own copy of the
state once it has applied the entry. A pop therefore reads its payloads from the queue logs of the
node you called. With offload off, a follower forwards each /api/ and /streams/ request to the
leader whole and relays the answer.
Two families never go to the leader. /api/v1/raft/* describes the node you asked (its id, its
role, its view of the members), so that node answers it. An ephemeral push, pop or ack lives in
the memory of the node that owns its partition, so the node you called relays it there; see
ephemeral queues. When no leader is known the answer is 503 no_leader,
and when a forwarded call cannot reach the leader it is 503 retry, both with Retry-After: 1.
Requests and responses
- Request bodies are JSON; send
Content-Type: application/json. A push and a transaction also take a binary body, from 2.3.0. - Responses are
application/json, exceptGET /metrics/prometheus(Prometheus text format), an empty pop, which is204 No Contentwith no body, and a pop asked for withframes=true(application/x-queen-pop, below). - A message
payloadis any JSON value. - Query parameters are camelCase, like the body fields:
consumerGroup,subscriptionMode,leaseSeconds,commitOnDelivery.
Authentication
The broker’s own authentication is off by default (JWT_ENABLED=false), and then every route is
open, so a bare broker belongs on a network you trust. In front of the internet, run the embedded
proxy, which authenticates API keys and sessions before a request reaches the broker.
| Credential | Header | Enabled by |
|---|---|---|
| JWT | Authorization: Bearer <jwt> |
JWT_ENABLED=true, plus JWT_SECRET, JWT_PUBLIC_KEY or JWT_JWKS_URL |
| Proxy API key | Authorization: Bearer qk_... |
the embedded proxy, which issues the keys |
| Proxy session | the proxy’s session cookie, or Authorization: Bearer <session token> |
signing in to the proxy (queenctl login, the console) |
| Client token | Authorization: Bearer qt_... |
a scoped key minting it at the proxy, POST /api/v1/tokens {sub, ttlSeconds?}: see client tokens |
With JWT on, every route requires an access level, shown in the route table below. A token’s role
comes from the role claim (JWT_ROLES_CLAIM) or the roles array (JWT_ROLES_ARRAY_CLAIM), and
the role names themselves are settings (JWT_ROLE_ADMIN and its siblings):
| Role (default name) | Grants |
|---|---|
admin |
every level |
read-write |
read-write, read-only and write-only routes |
read-only |
read-only routes |
write-only |
write-only routes: POST /api/v1/push, POST /api/v1/timers, POST /api/v1/ephemeral/push |
Write-only is deliberately not a step on a ladder: a producer token can push into a queue it can
never read. A missing or invalid token answers 401, a valid one with too little access 403. The
paths in JWT_SKIP_PATHS (default /health,/metrics/prometheus,/metrics,/) skip authentication.
An entry longer than / that ends in / skips the paths under it as well; / alone matches only
the root path, so the default does not open the API.
Tenancy header
With QUEEN_TENANCY_HEADER=true the broker reads the tenant of each request from
x-queen-tenant, which must be a UUID. A malformed value answers 400; an absent one means the
default tenant, 00000000-0000-0000-0000-000000000001. With the setting off (the default) every
request belongs to the default tenant.
For a client token the proxy also sends x-queen-scope, the names the
token may reach. The broker refuses a push, pop, ack, transaction, KV or timer call that touches
anything else (403 scope_denied), and any other route (403). The header only narrows: a caller
that sets it on the broker’s port restricts itself and nobody else.
Status codes
Most routes use plain HTTP semantics. A few carry their verdict in the body, and a client has to read it there:
| Answer | Meaning |
|---|---|
201 from POST /api/v1/push |
The request was handled. Each item has its own status: queued, duplicate (its transactionId is already in the partition’s dedup window, or repeated in the request) or error. |
200 from POST /api/v1/transaction with success: false |
Rolled back: nothing was written. reason says why. See transaction. |
200 from the KV, lock and timer routes |
A business verdict: applied: false (a lost putIfAbsent, a version mismatch, a write whose TTL was over when it was committed), acquired: false (a lock somebody else holds) or ok: false (cancelling a timer that is not pending). |
204 from a pop |
No message was available before the long-poll ended. |
503 outcome_unknown |
The leader changed while an ack, nack or DLQ move was being made durable. It may or may not have applied. |
503 retry, no_leader, timeout |
The call did not complete. Retry after Retry-After (1 s); a write may still have applied, so make it safe to repeat. |
503 standby |
The cluster is a standby and takes no writes until it is promoted. Nothing was applied. |
429 overloaded |
The node’s admission budget for writes (pushes, transactions, KV writes, timer schedules) stayed full for the whole hold. Retry after Retry-After. |
507 storage_full |
A node is above its disk high-water mark (QUEEN_RAFT_DISK_HIGH_PCT, 85%). Writes that grow storage are refused; acks and deletes still work. |
An engine error body is {"error": "<message>", "code": "<code>"}, plus "leader" on a 503
retry when the leader is known. The KV, lock and timer routes, the transaction route, the
ephemeral routes and the authentication layer have shapes of their own. Every code, and what a client does
with it, is on errors.
Health
GET /health answers 200 with "status": "healthy" when this node knows a leader, its apply
lag is within QUEEN_RAFT_READY_LAG_MS (2000 ms), and the leader it follows heard from a majority
of the voters within QUEEN_RAFT_READY_QUORUM_MS (5000 ms). Otherwise it answers 503 with
"status": "settling". The body carries engine, version and a raft block (role, leader,
term, applied, commit, lag, quorumAckMs, storageReady, clusterVersion, and link on
a cluster that is part of a standby pair). Those three conditions are the
whole check. The node contacts nobody to answer: it reads what replication already told it, so a
probe sees what this node knows, and a node that lost its majority says so five seconds later. It
does not prove that the cluster commits, which is why
monitoring pairs it with a write.
Routes
QueenMQ’s broker serves 116 method + path pairs. Every row below is read out of the router, the generic adapter behind it and the authorization table at build time.
Message plane
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/ack |
read-write | yes |
POST |
/api/v1/ack/batch |
read-write | yes |
POST |
/api/v1/lease/:leaseId/extend |
read-write | yes |
GET |
/api/v1/pop |
read-write | yes |
GET |
/api/v1/pop/queue/:queue |
read-write | yes |
GET |
/api/v1/pop/queue/:queue/partition/:partition |
read-write | yes |
POST |
/api/v1/push |
write-only | yes |
POST |
/api/v1/transaction |
read-write | yes |
Queues and partitions
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/configure |
read-write | yes |
GET |
/api/v1/resources/namespaces |
read-only | yes |
GET |
/api/v1/resources/overview |
read-only | yes |
GET |
/api/v1/resources/partitions |
read-only | yes |
GET |
/api/v1/resources/queues |
read-only | yes |
DELETE |
/api/v1/resources/queues/:queue |
admin | yes |
GET |
/api/v1/resources/queues/:queue |
read-only | yes |
GET |
/api/v1/resources/queues/:queue/depth |
read-only | yes |
GET |
/api/v1/resources/queues/:queue/sizes |
read-only | yes |
POST |
/api/v1/resources/quota |
admin | yes |
GET |
/api/v1/resources/tasks |
read-only | yes |
DELETE |
/api/v1/resources/tenant |
admin | yes |
Consumer groups
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/api/v1/consumer-groups |
read-only | yes |
DELETE |
/api/v1/consumer-groups/:group |
admin | yes |
GET |
/api/v1/consumer-groups/:group |
read-only | yes |
DELETE |
/api/v1/consumer-groups/:group/queues/:queue |
admin | yes |
POST |
/api/v1/consumer-groups/:group/queues/:queue/partitions/:partition/seek |
read-write | yes |
POST |
/api/v1/consumer-groups/:group/queues/:queue/seek |
read-write | yes |
POST |
/api/v1/consumer-groups/:group/subscription |
read-write | yes |
GET |
/api/v1/consumer-groups/lagging |
read-only | yes |
POST |
/api/v1/consumer-groups/positions |
read-write | yes |
Messages, DLQ and traces
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
DELETE |
/api/v1/dlq |
admin | yes |
GET |
/api/v1/dlq |
read-only | yes |
POST |
/api/v1/dlq/:id/replay |
read-write | yes |
GET |
/api/v1/messages |
read-only | yes |
DELETE |
/api/v1/messages/:partitionId/:transactionId |
read-write | yes |
GET |
/api/v1/messages/:partitionId/:transactionId |
read-only | yes |
POST |
/api/v1/messages/:partitionId/:transactionId/retry |
read-write | yes |
POST |
/api/v1/traces |
read-write | yes |
GET |
/api/v1/traces/:partitionId/:transactionId |
read-only | yes |
GET |
/api/v1/traces/by-name/:traceName |
read-only | yes |
GET |
/api/v1/traces/names |
read-only | yes |
Status, metrics and analytics
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/api/v1/analytics/dlq-signatures |
read-only | yes |
GET |
/api/v1/analytics/partition-liveness |
read-only | yes |
GET |
/api/v1/analytics/queue-lag |
read-only | yes |
GET |
/api/v1/analytics/queue-ops |
read-only | yes |
GET |
/api/v1/analytics/queue-parked-replicas |
read-only | yes |
GET |
/api/v1/analytics/retention |
read-only | yes |
GET |
/api/v1/analytics/system-metrics |
read-only | no |
GET |
/api/v1/analytics/worker-metrics |
read-only | no |
GET |
/api/v1/analytics/workload |
read-only | yes |
POST |
/api/v1/stats/refresh |
admin | no |
GET |
/api/v1/status |
read-only | yes |
GET |
/api/v1/status/analytics |
read-only | yes |
GET |
/api/v1/status/queues |
read-only | yes |
GET |
/api/v1/status/queues/:queue |
read-only | yes |
GET |
/health |
public | no |
GET |
/metrics |
public | no |
GET |
/metrics/prometheus |
public | no |
GET |
/status |
read-only | no |
Streams
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/streams/v1/claim |
read-write | yes |
POST |
/streams/v1/cycle |
read-write | yes |
GET |
/streams/v1/queries |
read-only | yes |
POST |
/streams/v1/queries |
read-write | yes |
POST |
/streams/v1/state/get |
read-only | yes |
POST |
/streams/v1/state/partitions |
read-only | yes |
Key/value state and timers
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/kv |
read-write | yes |
DELETE |
/api/v1/kv/:ns/*key |
read-write | yes |
GET |
/api/v1/kv/:ns/*key |
read-only | yes |
PUT |
/api/v1/kv/:ns/*key |
read-write | yes |
POST |
/api/v1/resources/kv/list |
read-only | yes |
GET |
/api/v1/resources/kv/namespaces |
read-only | yes |
POST |
/api/v1/timers |
write-only | yes |
GET |
/api/v1/timers/:queue |
read-only | yes |
DELETE |
/api/v1/timers/:queue/*timerKey |
read-write | yes |
GET |
/api/v1/timers/:queue/*timerKey |
read-only | yes |
Locks and semaphores
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/locks |
read-write | yes |
Ephemeral queues
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/ephemeral/_adopt |
read-write | yes |
POST |
/api/v1/ephemeral/_leaving |
read-write | no |
GET |
/api/v1/ephemeral/_ready |
read-write | no |
POST |
/api/v1/ephemeral/ack |
read-write | yes |
POST |
/api/v1/ephemeral/configure |
read-write | yes |
GET |
/api/v1/ephemeral/pop |
read-write | yes |
POST |
/api/v1/ephemeral/push |
write-only | yes |
DELETE |
/api/v1/ephemeral/queue/:_ |
read-write | yes |
DELETE |
/api/v1/ephemeral/queue/:queue |
read-write | yes |
GET |
/api/v1/ephemeral/queues |
read-only | yes |
GET |
/api/v1/ephemeral/queues/:queue/depth |
read-only | yes |
POST |
/api/v1/ephemeral/reset |
read-write | yes |
Operator surfaces
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/api/v1/system/ephemeral |
admin | no |
POST |
/api/v1/system/ephemeral |
admin | no |
GET |
/api/v1/system/kv-timers |
admin | no |
POST |
/api/v1/system/kv-timers |
admin | no |
GET |
/api/v1/system/link |
admin | no |
POST |
/api/v1/system/link/promote |
admin | no |
POST |
/api/v1/system/quota |
admin | no |
POST |
/api/v1/system/quotas |
admin | no |
GET |
/api/v1/system/raft/membership |
admin | no |
POST |
/api/v1/system/raft/membership/learners |
admin | no |
DELETE |
/api/v1/system/raft/membership/members/:id |
admin | no |
POST |
/api/v1/system/raft/membership/promote |
admin | no |
PUT |
/api/v1/system/raft/membership/voters |
admin | no |
GET |
/api/v1/system/shared-state |
admin | no |
Cluster (raft)
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/api/v1/raft/liveness |
read-write | no |
GET |
/api/v1/raft/members |
read-write | no |
GET |
/api/v1/raft/status |
read-write | no |
Reads by offset
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
POST |
/api/v1/feed |
read-only | yes |
POST |
/api/v1/fetch |
read-only | yes |
POST |
/api/v1/fetch/offsets |
read-only | yes |
POST |
/api/v1/partitions/changed |
read-only | yes |
Connectors
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/api/v1/connectors |
read-only | yes |
DELETE |
/api/v1/connectors/:name |
admin | yes |
GET |
/api/v1/connectors/:name |
read-only | yes |
PUT |
/api/v1/connectors/:name |
admin | yes |
POST |
/api/v1/connectors/:name/resync |
admin | yes |
Dashboard identity (broker-direct)
| Method | Path | Access level | Tenant-scoped |
|---|---|---|---|
GET |
/auth/login |
public | no |
POST |
/auth/logout |
public | no |
GET |
/auth/me |
public | no |
87 of these handlers resolve a tenant from the request; 22 /api/v1/* routes do not and are therefore cell-wide reads or operator surfaces.
POST /api/v1/ephemeral/_adopt and _leaving are broker-to-broker hand-over calls: they also
require the forward mark that only another node sets (and the cluster token when one is
configured), and the proxy never lets a tenant reach them.
GET /api/v1/system/link and POST /api/v1/system/link/promote are the two calls of a
standby cluster: where it is in its source’s log, and the switch that makes
it an ordinary cluster. What a standby reads from its source is not on this port: it is served on
the source’s raft port, under /link/v1/, to the holder of the source’s QUEEN_LINK_TOKEN.
Message browsing
GET /api/v1/messages lists messages newest first, filtered by queue, partition, namespace,
task and status. limit defaults to 200 and is clamped to 1 through 1000; offset defaults to
0. from is inclusive and defaults to one hour ago. to defaults to now and is rounded to the
start of the next minute, which is exclusive: to=2026-10-06T20:04:00Z includes messages before
20:05:00Z.
The queue-log path uses timestamps and offsets in the indexes to select the page before reading
payloads. A historical window therefore skips newer payloads, and an append containing only
messages skipped by offset is not read. The request still gathers partition and cursor metadata;
deep offsets and selective status filters can require more metadata work. The legacy segment
path reads backwards in chunks and can scan payloads newer than to.
Reads by offset
Three routes read a partition’s log by position. None of them takes a lease or moves a cursor, so
two readers asking the same question get the same answer and nothing has to be acked. The Kafka
facade consumes through them, and they are also the right tool for a replay, an audit or a sink
that keeps its own position. Each is served from the answering node’s own state, with no read
barrier: a follower answers from what it has applied. Every SDK wraps the first and the last as two
queue methods, fetch and changedSince, which also follow the pages and the high watermark for
you: see reads by offset in the clients.
POST /api/v1/fetch
curl -s localhost:6632/api/v1/fetch -H 'content-type: application/json' -d '{
"entries": [{"queue": "orders", "partition": "customer-42", "offset": 0, "maxBytes": 1048576}],
"maxWaitMs": 5000, "minBytes": 1}'{"entries": [{"queue": "orders", "partition": "customer-42",
"records": [{"offset": 0, "transactionId": "order-9137-created",
"payload": {"orderId": 9137}, "ts": "2026-10-02T09:14:03.512887Z"}],
"highWatermark": 1, "logStartOffset": 0}]}| Field | Rule |
|---|---|
entries |
At most 1024. Each names a queue, a partition (a string, a number, or absent for Default) and a non-negative offset; a negative one answers 400. |
entries[].maxBytes |
Default 1 MiB, clamped to 1 byte to 8 MiB. |
maxBytes (top level) |
Optional, from 2.3.0: a ceiling for the whole call, counted in payload bytes. The entries are read in order while any of it is left, each for no more than what is left, and an entry reached with none left answers its bounds and no records. The first record of an entry is read whatever it weighs, so a call passes its ceiling by one record at most. Without it every entry is read to its own maxBytes. |
maxWaitMs |
Default 0, at most 30,000. With a wait, the call holds until minBytes (default 1) are readable across the entries or the wait ends. A call that has read nothing also answers, empty, once it has waited QUEEN_FETCH_TOPIC_WAKE_MS (5 ms) and another partition of a queue it reads was written on the node, so a caller can ask again for partitions it left out; 0 turns that off. |
An entry’s error |
UNKNOWN_TOPIC_OR_PARTITION for a queue that does not exist; OFFSET_OUT_OF_RANGE for an offset below logStartOffset or above highWatermark. A partition nobody has written yet answers no records and no error. |
highWatermark is the next offset the partition will assign; logStartOffset is the first one
retention has kept.
POST /api/v1/fetch/offsets
Turns a time into an offset: for each entry, the first offset appended at or after timestamp
(epoch milliseconds, or an ISO-8601 time). At most 1024 entries.
{"entries": [{"queue": "orders", "partition": "customer-42", "timestamp": "2026-10-02T09:00:00Z"}]}{"entries": [{"queue": "orders", "partition": "customer-42", "offset": 42,
"ts": "2026-10-02T09:00:00.004211Z", "highWatermark": 97, "logStartOffset": 0}]}offset and ts are null when nothing was appended that late, and you start at
highWatermark; a time older than the log answers its first retained offset. “Appended” means the
broker’s clock when the leader planned the write, never a time inside your payload. The lookup is a
binary search over the partition’s per-append rows, about log2(partition length) seeks, and, for
messages older than the rows the store still holds, over the queue log’s index; no payload is
read.
POST /api/v1/partitions/changed
Maps a queue: its partitions with their lastOffset, logStart and lastWriteAt, by name, or
only those written since a time.
{"entries": [{"queue": "orders", "since": "2026-10-02T09:00:00Z", "limit": 1000}]}Each entry answers partitions and next, a cursor to pass back as after while the page was
full; limit defaults to 1000 and is capped there. A queue that does not exist answers
UNKNOWN_TOPIC_OR_PARTITION, a cursor that does not parse BAD_CURSOR. At most 1024 entries.
POST /api/v1/feed
Every push to a tenant’s queues, in the order the log committed them, read by position. A position
is the log entry that wrote a message: one number orders every queue of the tenant, and the pushes
of one transaction share it. Like the reads above, nothing is leased, acked or moved, and every
consumer group still gets its messages. The JavaScript client wraps it as queen.feed() and
Stream.fromFeed().
curl -s localhost:6632/api/v1/feed -H 'content-type: application/json' -d '{
"from": "earliest", "queues": ["orders*"],
"where": [{"field": "data.country", "op": "=", "value": "IT"}],
"maxWaitMs": 5000}'{"applied": 12, "caughtUp": true,
"entries": [{"id": "0193f1c2-5d4e-7a10-9b2c-4f6a8e1d2c3b", "kind": "push", "offset": 0,
"partition": "customer-42", "partitionId": "0193f1c2-5d40-7000-8000-1a2b3c4d5e6f",
"payload": {"orderId": 9137, "country": "IT"}, "position": 7, "queue": "orders",
"transactionId": "order-9137-created", "ts": "2026-11-06T09:14:03.512887Z"}],
"next": 13, "resolvedTs": "2026-11-06T09:14:03.600000Z"}An entry carries headers when the message has some. A message a queue holds by a link (a
reading queue’s, or a link’s target) shows read through it, with
the source’s id, transaction id and payload, and "link": {"queue", "partition", "offset"}, where it
is at its source: a reader of every queue can tell a message it already has.
| Field | Rule |
|---|---|
from |
A position (included), "now" (the default: only what comes next) or "earliest". Send an answer’s next back to read on. |
since |
Only messages created at or after this time (ISO-8601). Files holding only older messages are not read. |
queues |
Names or patterns (* any run of characters, ? one); every queue of the tenant when absent. At most 256. |
partitions |
Partition names, in whichever queue is read. At most 1000. |
where |
Conditions that must all hold: a list of {field, op, value}, or one string in the where language (data.country = 'IT' and headers.type = 'order.paid'). Fields: queue, partition, transactionId, offset, position, data and data.<path> (a number in the path indexes an array), headers.<name>. Ops: =, !=, <, <=, >, >=, in (the value is an array), exists, prefix, !prefix (a string that does not start with it). A field the message does not have holds for no op, != and !prefix included. At most 16. |
kinds |
["push"], the one kind served so far. |
maxRecords |
Messages in one answer: default 1,000, at most 10,000. |
maxBytes |
Payload bytes in one answer: default 1 MiB, at most 16 MiB. |
maxWaitMs |
Default 0, at most 30,000. With a wait, a read that is caught up and found nothing waits for a push to one of the queues it reads, or to a queue it names that does not exist yet. |
shard |
{count, index, queues?}: only the partitions whose name hashes to index of count (FNV-1a, 32 bit, over the name’s UTF-8 bytes, modulo count), left out before their payload is read. In each sealed file of a queue log the broker reads only the shard’s records, through the file’s index; the file still being written is read through. With queues (names or patterns), only those queues are split and the others are read whole. count from 1 to 4096. |
| An unknown field | 400: a typo would widen the read. |
An answer holds whole positions: a cap that falls inside a transaction’s pushes lets that position
through and stops before the next. next is where to read on; caughtUp says the answer reached
applied, the last position this node has applied; resolvedTs is a time such that every message
stamped at or before it is in this answer or an earlier one, the same promise as safeTime above.
It does not go back on a running node. Another node, or the same node after a restart, can answer
a lower one, so a reader keeps the highest it has seen.
A filter that drops everything still moves next past what it read.
A leader does not serve it. A node that leads the tenant’s raft group of a cluster answers 421 with
"code": "feed_on_leader" and the followers to ask (nodeId, httpAddr); the JavaScript client
goes there by itself. A caller that cannot reach the followers sends x-queen-feed-relay: 1, and
the leader hands the read to a follower and passes its answer back: the follower reads the log, the
leader only passes the bytes on. The proxy sends that header on every feed read, so a read through
the proxy is served whichever node it lands on; the route there needs a consumer’s authority, like
/api/v1/fetch. A single node serves it. QUEEN_FEED_ON_LEADER=true lets a leader serve it too. The read never goes past what the answering node has applied: its queue logs are also the raft
log, and their tail can hold entries a new leader may still cut.
Binary bodies
From 2.3.0 the push, ack, pop and transaction routes take compact forms next to the JSON ones.
They are what the SDKs send when their
binary push, push compression and framed pop
options are on; a JSON request is answered as before, and a broker up to 2.2.0 answers a binary
body with 400. Admission, commands and verdicts are those of the JSON forms. Every integer is
little-endian, and a len, text pair is a length followed by that many bytes of UTF-8.
A binary push
POST /api/v1/push reads a body that starts with QPB1 as:
"QPB1" | u8 flags | [u32 raw_len, with flag 1] | body
body: u32 groups | per group: u16 len, queue | u16 len, partition | u32 n
| n x ([u16 len, transactionId, with flag 4] | u32 len, payload)| Flag | Meaning |
|---|---|
| 1 | The body is one zstd frame that inflates to raw_len bytes (at most 256 MiB). |
| 2 | Answer with the counts only: {"count":3,"queued":3,"duplicate":0,"error":0} in place of one object per message. |
| 4 | Every item carries its transactionId; an empty one is minted by the broker. |
| 8 | The groups are frames the client built and compressed, below. |
A payload must be one JSON document, as in the JSON body, and is checked. A binary push carries no
traceId. With flag 8 the body is:
u32 groups | per group: u16 len, queue | u16 len, partition | u32 n | u32 z_len | zwhere z is one zstd frame, declaring its content size, of the group’s n messages in the layout
the queue log stores:
u32 body_len | u8 0 | u8[16] message id (a version-7 UUID) | u16 len, transactionId | payloadThe broker inflates each group and checks every frame. When it has nothing to add to a group (no
producer identity, a queue that does not encrypt, no transactionId twice in the request), it
stores the client’s compressed bytes as they arrived and ships them to its followers, and
compresses nothing itself. An encryption key on the broker changes this only for the queues that
encrypt (since 2.4.0; before, for every queue). Flags 1 and 8 together are refused: a framed body is already compressed, and the weight of
each group has to be readable from its header. A body the broker cannot follow answers 400 with
the code bad_body.
An ack answered with counts
"answer": "counts" in the body of POST /api/v1/ack or /api/v1/ack/batch answers
{"count":100,"success":100,"failed":0,"error":null}, where error is the first refusal’s
reason, in place of one result per message. A broker up to 2.2.0 ignores the key and answers the
list.
A pop answered with the stored records
frames=true on the three pop routes answers application/x-queen-pop: the records as the queue
log holds them, compressed frames included, so the broker inflates and renders nothing.
"QPF1" | u8 1 | u32 len, a JSON object with the answer's own keys
u16 len, queue | u16 len, leaseId | u16 len, consumerGroup | u32 claims
per claim: u64 partitionId | u16 len, partition | u64 start | u64 end | u32 deliveryAttempt | u32 records
per record: u64 base_offset | i64 created_at_us | u32 count | u8 codec (0 raw, 1 zstd) | u32 len | bytesA record’s bytes are count messages in the stored layout above; message i has offset
base_offset + i and belongs to the delivery when that offset lies in its claim’s start to
end, both included. The JSON object is {"frames":true} plus what the JSON answer carries
beside its messages. Recognise the form by its first four bytes, not by the request: the broker
answers in JSON when a record it would send holds an encrypted message (a queue that encrypts, or
one whose encryption was switched off while older messages are still encrypted; before 2.4.0,
whenever the broker had an encryption key), when a claim is conflated, or when a claimed record
cannot be read as stored. An empty pop is 204, as ever.
A binary transaction
POST /api/v1/transaction reads a body that starts with QTB1 as:
"QTB1" | u8 flags | u32 len, head | u32 groups | the groups of a framed pushThe head is the JSON transaction body without its push operations (it may be empty), and the
pushes are the groups, built as for flag 8 above. In the answer’s results the head’s operations
come first, then the groups’ messages in the order written, then the riders (KV writes and timers),
so a client that interleaved pushes and acks puts the results back in its own order. Flag 2
leaves the pushes’ and acks’ results out and adds "pushed", "duplicate" and "acked"; any
other flag bit answers 400.
Control plane: /api/cp
With the embedded proxy on, a node also serves a small control-plane API under /api/cp: how a
provisioning script, an operator or a cloud control plane manages tenants, clusters and API keys.
The proxy keeps that state in the broker’s own replicated KV, so there is no database to run
beside it. The surface is built for an at-least-once caller: repeating a provision, a key
registration, a purge or a delete that already took effect answers success with the same ids. The
exception is POST /api/cp/tenants, which answers 409 conflict for a slug that exists;
POST /api/cp/clusters is the call that ensures a tenant and its cluster idempotently.
The surface exists only when QUEEN_PROXY_CP_TOKEN is set. Every call sends the token in
x-queen-cp-token; a wrong token answers 401, and with the variable unset every route answers 404.
Request bodies are capped at 1 MiB (413 above that), and the token is checked before any of the
body is read. A call that acts on broker data (purge, queues, configure) always acts on the
cluster’s own broker tenant, never on one the request names, and it refuses the default tenant and
the proxy’s own.
| Method | Path | What it does |
|---|---|---|
POST |
/api/cp/bootstrap |
Creates a tenant, its cluster, an admin user and an API key in one call. Body: tenant_slug, admin_email; optional tenant_name, cluster_slug (default the tenant slug), plan (default free), password, key_name. |
POST |
/api/cp/provision |
Tenant, cluster, user, role, API key and limit overrides in one batch, with ids the caller chose. Body: tenant_slug, cluster_slug, plan, user_id (a UUID), email, role, key_name, key_hash, scopes; optional tenant_name, overrides. 503 unavailable until the node has seeded its state. |
POST |
/api/cp/tenants |
Creates a tenant (slug, optional name). 201 with its id. |
PUT |
/api/cp/tenants/:slug/status |
Sets status: active, grace, suspended or deleting. |
POST |
/api/cp/tenants/:slug/purge |
Deletes the broker data of every cluster of a deleting tenant. Repeat until the answer says done: true. |
DELETE |
/api/cp/tenants/:slug |
Deletes a tenant that is deleting and purged; ?force=true skips both checks. |
GET |
/api/cp/clusters |
Every cluster; ?plan=<code> keeps one plan’s. |
POST |
/api/cp/clusters |
Ensures a cluster and its tenant exist (tenant_slug, slug; optional tenant_name, plan, cell_id). 201 when created, 200 when it already existed. |
GET |
/api/cp/clusters/:slug |
The cluster with its tenant, plan, statuses and overrides. |
GET |
/api/cp/clusters/:slug/queues |
The broker’s queue listing for the cluster, query string passed through. |
POST |
/api/cp/clusters/:slug/configure |
The broker’s configure for the cluster ({"queue", "options"} passed through). Refused with 409 deleting during a wipe. |
PUT |
/api/cp/clusters/:id/overrides |
Sets the cluster’s limit overrides: a JSON object, or null to clear them. |
PUT |
/api/cp/clusters/:id/status |
Sets status: active, push_blocked, suspended or deleting. |
GET |
/api/cp/clusters/:id/usage |
The last hour of metered minutes, summed over the nodes. |
POST |
/api/cp/activity |
For up to 256 cluster slugs: last traffic, first push, last key use and retained bytes. Absent data is null, never 0. |
POST |
/api/cp/keys |
Registers an API key the caller has already hashed (cluster_id, name, key_hash, scopes); the plaintext never reaches the proxy. 201 for a new key, 200 when the cluster already holds a live key with that hash. |
DELETE |
/api/cp/keys/:id |
Revokes a key: 200 with already_revoked, or 404 key_unknown. |
Slugs are DNS labels (a-z, 0-9 and -, at most 63 characters); :id is a UUID. Errors use the
proxy’s {"error", "code"} envelope, and the codes are listed on
errors.
OpenAPI
Two OpenAPI documents are generated from the routers and published with the site:
/openapi/queen-broker.json: the broker, every route in the table above./openapi/queen-proxy.json: the proxy’s own routes (sign-in, the console, the operator API and/api/cp).
Most request bodies are not derived from a Rust type yet, so the documents describe paths and parameters more completely than bodies. For a body, the pages of this site are the contract, above all transaction.
| Document | Operations | Paths | Request bodies derived from a type | Request bodies opaque |
|---|---|---|---|---|
queen-broker.json |
116 | 104 | 7 | 34 |
queen-proxy.json |
56 | 47 | 0 | 0 |