Skip to content

HTTP API reference and OpenAPI

Base URL, which node to call, authentication, status codes, every route the broker serves, reads by offset, the control-plane API and the OpenAPI documents.

Updated View as Markdown

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, except GET /metrics/prometheus (Prometheus text format), an empty pop, which is 204 No Content with no body, and a pop asked for with frames=true (application/x-queen-pop, below).
  • A message payload is 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.

Why
a reader that sees every queue in one order, from one position, can route, mirror, audit and react without a consumer group per queue, and reading on followers keeps all of it off the node that orders the writes.

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 | z

where 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 | payload

The 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 | bytes

A 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 push

The 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:

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
Navigation

Type to search…

↑↓ navigate↵ selectEsc close