Plain HTTP. JSON in, JSON out.

All requests live under /api/v1. JSON request bodies, JSON responses. Bearer token in the Authorization header when JWT is enabled. Every endpoint below was exercised against a live server while writing this page.

Endpoint summary

Health

curl http://localhost:6632/health

Returns {"status":"healthy","database":"connected","version":"…",…}. Always public, never gated by auth.

Metrics & Prometheus

Two endpoints, both public (in JWT_SKIP_PATHS by default), neither needs a bearer token.

JSON metrics

curl http://localhost:6632/metrics

Lightweight JSON snapshot intended for ad-hoc inspection and the bundled SDKs' Admin.metrics() helper. Reports the live DB pool stats plus a stub for uptime / requests / messages — for a real telemetry surface use /metrics/prometheus below.

Prometheus exposition

curl http://localhost:6632/metrics/prometheus

Returns text/plain; version=0.0.4; charset=utf-8 in the standard Prometheus text exposition format. Each scrape:

• reads in-process state for per-replica live gauges (process / db pool / threadpools / file buffer / sidecar / shared-state) — no DB hit;
• performs one DB call to queen.get_prometheus_metrics_v1() for cluster-wide series (lifetime totals, latest-bucket per-queue and per-worker, DLQ depth).

Metric inventory

Prometheus scrape config

scrape_configs:
  - job_name: queen
    metrics_path: /metrics/prometheus
    scrape_interval: 15s
    static_configs:
      - targets:
          - 'queen-host-1:6632'
          - 'queen-host-2:6632'
          - 'queen-host-3:6632'

Kubernetes pod annotations

podAnnotations:
  prometheus.io/scrape: "true"
  prometheus.io/path:   "/metrics/prometheus"
  prometheus.io/port:   "6632"

Useful PromQL recipes

# Cluster-wide push throughput (msg/s)
max(rate(queen_cluster_push_messages_total[1m]))

# Per-queue pop throughput (msg/s) using the per-minute gauge
sum by (queue) (queen_queue_pop_messages_per_minute) / 60

# Per-queue p100 pop lag in seconds
max by (queue) (queen_queue_pop_lag_milliseconds{stat="max"}) / 1000

# DB connection saturation per replica
queen_db_pool_active / queen_db_pool_size

# Worker imbalance: max event-loop lag across workers
max by (instance) (queen_worker_event_loop_lag_milliseconds{stat="max"})

# Cluster ack failure ratio over 5m
max(rate(queen_cluster_ack_total{result="failed"}[5m]))
  / clamp_min(max(rate(queen_cluster_ack_total[5m])), 1)

# Stale metrics alert: bucket older than 3 minutes
queen_queue_metrics_age_seconds > 180

# DLQ depth alert
queen_dlq_depth > 0

Configure a queue

curl -X POST http://localhost:6632/api/v1/configure \
  -H 'Content-Type: application/json' \
  -d '{
    "queue":"orders",
    "namespace":"billing",
    "task":"process-invoice",
    "options":{
      "leaseTime":300,
      "retryLimit":3,
      "priority":5,
      "retentionSeconds":3600,
      "completedRetentionSeconds":86400,
      "encryptionEnabled":false,
      "deadLetterQueue":true,
      "dlqAfterMaxRetries":true
    }
  }'

Push

curl -X POST http://localhost:6632/api/v1/push \
  -H 'Content-Type: application/json' \
  -d '{
    "items":[
      {
        "queue":"orders",
        "partition":"user-123",
        "payload":{"orderId":1,"amount":99.99},
        "transactionId":"order-1-v1",
        "traceId":"019dc9-..."
      }
    ]
  }'

partition defaults to "Default". transactionId is server-generated if omitted; provide your own for idempotent pushes.

Optional: server-side push buffering (QoS 0)

For very high-rate fire-and-forget pushes, ask the server to batch-flush:

curl -X POST http://localhost:6632/api/v1/push \
  -H 'Content-Type: application/json' \
  -d '{
    "items":[{"queue":"events","payload":{"type":"login"}}],
    "bufferMs":100,
    "bufferMax":100
  }'

Pop

curl 'http://localhost:6632/api/v1/pop/queue/orders?consumerGroup=processors&batch=10&wait=true&timeout=30000'

Response shape:

{
  "success": true,
  "queue":         "orders",
  "partition":     "Default",
  "partitionId":   "c0715-...",
  "leaseId":       "019dc9-...",
  "consumerGroup": "__QUEUE_MODE__",
  "messages": [
    {
      "transactionId": "019dc9-...",
      "partitionId":   "c0715-...",
      "partition":     "Default",
      "leaseId":       "019dc9-...",
      "consumerGroup": "__QUEUE_MODE__",
      "data":          { "orderId": 1, "amount": 99.99 },
      "createdAt":     "2026-04-26T10:59:28.267966Z",
      "retryCount":    0,
      "producerSub":   null
    }
  ],
  "partitionsClaimed": 1
}

Each message carries its own partitionId, partition, leaseId, and consumerGroup, these per-message fields are authoritative for ACK and lease-renew calls. The top-level partitionId / partition reflect the first claimed partition (kept for back-compat with single-partition pops). partitionsClaimed is the number of distinct partitions the response actually drained.

Multi-partition pop (partitions=N)

Drain up to N partitions in a single round-trip. Designed for queues with many partitions where each partition only has a handful of new messages per polling interval, claiming one partition per call wastes bandwidth. The server walks eligible partitions in scan order, claims each one via a non-blocking advisory lock, and accumulates messages until either:

• the combined message count reaches batch, or
• partitions partitions have been claimed, or
• no more eligible partitions remain.

All claimed partitions share a single leaseId, so a single POST /api/v1/lease/:leaseId/extend call extends every claimed partition's lease atomically. Only valid on the wildcard route (/api/v1/pop/queue/:queue); the per-partition route silently treats partitions>1 as 1.

curl 'http://localhost:6632/api/v1/pop/queue/events?batch=200&partitions=50&wait=true'

{
  "success": true,
  "queue":         "events",
  "partition":     "p7",                    // first claimed partition (back-compat)
  "partitionId":   "8f...",                 // first claimed partitionId (back-compat)
  "leaseId":       "worker-abc",            // shared across all claimed partitions
  "consumerGroup": "__QUEUE_MODE__",
  "messages": [
    {"transactionId": "...", "partitionId": "8f...", "partition": "p7",  "leaseId": "worker-abc", "data": {...}, ...},
    {"transactionId": "...", "partitionId": "12...", "partition": "p12", "leaseId": "worker-abc", "data": {...}, ...},
    {"transactionId": "...", "partitionId": "5e...", "partition": "p3",  "leaseId": "worker-abc", "data": {...}, ...}
  ],
  "partitionsClaimed": 8
}

Ack

curl -X POST http://localhost:6632/api/v1/ack \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId":"<tx>",
    "partitionId":"<pid>",
    "status":"completed"
  }'

curl -X POST http://localhost:6632/api/v1/ack \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId":"<tx>",
    "partitionId":"<pid>",
    "status":"failed",
    "error":"timeout calling downstream",
    "consumerGroup":"processors"
  }'

curl -X POST http://localhost:6632/api/v1/ack/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "consumerGroup":"processors",
    "acknowledgments":[
      {"transactionId":"tx-1","partitionId":"pid-1","status":"completed"},
      {"transactionId":"tx-2","partitionId":"pid-2","status":"failed","error":"validation"}
    ]
  }'

Transaction (atomic ack + push)

curl -X POST http://localhost:6632/api/v1/transaction \
  -H 'Content-Type: application/json' \
  -d '{
    "operations":[
      {
        "type":"ack",
        "transactionId":"<input-tx>",
        "partitionId":"<input-pid>",
        "status":"completed",
        "consumerGroup":"analytics"
      },
      {
        "type":"push",
        "items":[
          {"queue":"next-stage","partition":"p2","payload":{"derived":true}}
        ]
      }
    ]
  }'

All operations execute in a single PostgreSQL transaction. Either everything commits, or nothing does. Use this for exactly-once message handoff between queues.

Extend a lease

curl -X POST http://localhost:6632/api/v1/lease/<leaseId>/extend \
  -H 'Content-Type: application/json' \
  -d '{"seconds":60}'

Use the leaseId returned by pop. Most clients renew leases for you when you set renewLease(true, intervalMillis) on the consumer.

For multi-partition pops (partitions=N), all claimed partitions share one leaseId, a single extend call updates every partition's lease in one shot. No need to call extend per partition.

Resources

Status & analytics

These are what the dashboard renders. Useful for embedding Queen metrics into your own ops dashboards.

Dead-letter queue

curl 'http://localhost:6632/api/v1/dlq?queue=orders&from=2025-12-01&to=2025-12-31&limit=100'

Each entry includes the original message data, the errorMessage, retryCount, original timestamps, and the consumer group it failed under.

Consumer groups

Returns all groups (named groups + the implicit __QUEUE_MODE__) with member counts, total offset lag, max time-lag, and per-queue/partition detail. State is one of Stable, Lagging, or Dead.

Auth header

When JWT is enabled (JWT_ENABLED=true), every request that isn't on the public list (/health, /metrics, /metrics/prometheus, dashboard) needs:

curl http://localhost:6632/api/v1/resources/queues \
  -H "Authorization: Bearer $QUEEN_TOKEN"

See Server setup → JWT for HS256 / RS256 / EdDSA configuration and the role-based gating model.