POST /api/v1/push

One call writes one or more messages to one or more queues. Access level write-only, which is the only route a write-only token can reach. The response is always a top-level array with one element per request item, in request order.

Request

{
  "items": [
    {
      "queue": "orders.created",
      "partition": "customer-42",
      "transactionId": "order-8891-created",
      "payload": { "orderId": 8891, "total": 4200 }
    }
  ]
}

Notes that change behaviour:

• payload is the wire field name. The JavaScript and Python clients also accept data on an item and rename it to payload before sending; the Go client’s field is Payload. On raw HTTP, data is not recognised, and because unknown keys are ignored an item carrying data but no payload fails the body parse with a 400: payload is required.
• payload may be any JSON value: object, array, string, number, boolean or null. It is stored verbatim and spliced back into the pop response without re-serialization.
• traceId is silently ignored on this route. The push path always stores a null trace id, so every message produced through /api/v1/push comes back from a pop with traceId: null. A trace id can only be attached at write time through POST /api/v1/transaction.
• Items in one call may target different queues and different partitions.
• "items": [] is accepted and returns 201 with an empty array.
• When authentication is enabled, the validated token’s sub is stamped onto every frame and echoed by pops as producerSub. A producerSub supplied in the request body is never honoured.

Queues and partitions are created by pushing

If the queue does not exist, the first push creates it, together with its configuration row and its first partition. namespace and task are derived from a dotted name (orders.created becomes namespace orders, task created), so a queue that was never explicitly configured is still discoverable by a namespace or task pop. Queue options keep their defaults, which is where the two-valued leaseTime comes from: a queue created implicitly by a push leases for 60 seconds, while a queue created or updated through /api/v1/configure leases for 300 seconds.

Partitions are created on first push to that partition name, and deleted automatically only once they are empty and have been idle for PARTITION_CLEANUP_DAYS (30). A push to a name whose partition was reclaimed simply creates it again, with a new id and offsets from 0.

Response

201 Created, Content-Type: application/json, a top-level array:

[
  {
    "index": 0,
    "message_id": "0198f2c1-4d3a-7c10-9f2b-6a1e5d0c7b83",
    "transaction_id": "order-8891-created",
    "queueName": "orders.created",
    "status": "queued"
  }
]

The mixed casing (message_id and transaction_id snake_case, queueName camelCase) is the wire contract, not a typo, and clients depend on it.

There is no partition, no partitionId, no offset and no createdAt in a push result. The offset a message landed on is never returned to a producer; positions are internal to the storage engine and are only ever used through cursors.

Item statuses

Replay from the spool preserves the transactionId, so deduplication makes it idempotent: a message that was both buffered and (by your own retry) pushed again lands once.

Status codes

Atomicity

Items are grouped by (queue, partition), and each group becomes one segment. The commit boundary is the group, not the request. A push spanning three partitions can have one group committed and another failed, which is exactly what the per-item statuses report. If you need several writes to land together, use POST /api/v1/transaction, which runs the whole bundle in one PostgreSQL transaction.

The handler does not answer until every group has resolved, so the call’s latency includes the broker’s write-coalescing hold window: concurrent pushes to different partitions are bundled into a single database transaction, which is what makes one commit carry many messages.

Deduplication

Deduplication is on by default, exact, and scoped to one partition. The key is the item’s transactionId; the bound is the queue’s dedupWindowSeconds, whose default is 3600. Setting it to 0 disables deduplication for that queue.

Two layers run, in this order:

1. Within one request. The first item for a given (queue, partition, transactionId) wins. Later items in the same body produce no frame and come back duplicate, carrying the winner’s message_id.
2. In the database. Before allocating an offset, the push probes the partition’s transaction index for the incoming hashes while holding the partition’s row lock. A hit returns duplicate having written nothing at all: there is no insert to roll back, and no subtransaction. A clean probe proceeds to allocate.

Because the probe happens under the same row lock that serializes writes to the partition, two concurrent pushes of the same transactionId cannot both succeed.

const res1 = await client
.queue('test-queue-v2')
.push([{ transactionId: 'test-transaction-id', data: { message: 'Hello, world!' } }])

const res2 = await client
.queue('test-queue-v2')
.push([{ transactionId: 'test-transaction-id', data: { message: 'Hello, world!' } }])
// res1[0].status === 'queued', res2[0].status === 'duplicate'

What you get back for a duplicate is the original message’s id, resolved from the stored segment. If the original can no longer be read (retention removed its segment, for instance), the id comes back as the all-zeros UUID 00000000-0000-0000-0000-000000000000, the “original unknown” sentinel. The status is still duplicate.

Examples

const res = await client
.queue('test-queue-v2')
.push([{ data: { message: 'Hello, world!' } }])

res = await client.queue("test-queue-v2").push([{"data": {"message": "Hello, world!"}}])

responses, err := client.Queue(queueName).Push(payload).Execute(ctx)
if err != nil {
	t.Fatalf("Failed to push message: %v", err)
}

Raw HTTP, with an explicit deduplication key:

curl -sS -X POST http://localhost:6632/api/v1/push -H 'content-type: application/json' -d '{"items":[{"queue":"orders.created","partition":"customer-42","transactionId":"order-8891-created","payload":{"orderId":8891}}]}'

Encryption at rest

If the queue has encryptionEnabled and the broker has a valid QUEEN_ENCRYPTION_KEY, payloads are encrypted before they are packed into a segment, and pops decrypt them transparently. A malformed or wrong-length key disables encryption and stores plaintext with only a warning in the log. It is not a boot failure and not a push failure. Self-hosting covers key handling.