---
title: "Reserve messages from the queue"
method: POST
path: "/v1/queue.reserve"
tags: ["Querator V1"]
---

# Reserve messages from the queue

`POST /v1/queue.reserve`

Reserve a message from the requested queue.  When a message is reserved by a consumer, that consumer gains exclusive rights to the message. No other consumer will be provided the same message unless the `reserve_deadline` has expired 
and the consumer with the reservation has not marked the message via  `/queue.complete` or `/queue.defer`

If a message is not acknowledge via `/queue.complete` within the `reserve_deadline` period it will be offered to another consumer.

### Timeout Semantics
The call will return when a reservation is successful or when `request_timeout` has been reached. If the call returns with a 454 `Retry Request` response code, this means there were no items in the queue and the `request_timeout` was reached. In this case the client should retry the reserve request.

The client should NOT cancel the request before `request_timeout` has been reached. If the call fails to return after `request_timeout` is reached the client can safely cancel the request.

## Request body

- QueueReserveRequest
  - `queue_name` string, required — The name of the queue
  - `client_id` string, required — A unique id which identifies this client. Duplicate client id's are not allowed
  - `request_timeout` string, required — The duration this request should block before the client will cancel the request.
  - `batch_size` integer — The maxium number of items to be reserved for this request

## Response `200`

- QueueReserveResponse
  - `items` QueueReserveItem[], required
    - `id` string, required — A unique id which identifies an item in a queue
    - `encoding` string — A user specified field which indicates the encoding the user used to encode the payload
    - `kind` string — A Kind or Type the payload contains. Consumers can use this field to determine handling of the payload prior to unmarshalling
    - `reference` string — This is a user specified field that can be used by the consumer to determine handling of the queue item without needing to unmarshall the payload.
    - `attempts` integer — The number of times this item has been deferred or reservation timed out during processing by a consumer
    - `reserve_deadline` string, required — The date time that Querator will offer up this item to another consumer. If the consumer reserving this item has not marked it complete. The consumer can use this date to decide if it should finalize it's work if the timeout date has expired.
    - `bytes` string — The payload of the item as an array of raw bytes with no predetermined character set. NOTE: If `Content-Type: application/json` is used when communicating with Querator, the 'bytes' field will be encoded as base64. This is because byte fields (unlike string fields) can contain non-UTF8 binary data, and since that cannot be directly represented in JSON, we have to base64 encode it.
  - `queue_name` string, required — The name of the queue the reserved items are from
  - `partition` integer, required — Partition the reserved items are from

## Changes

- **2024-09-15** `ba3240950bb2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kapetan-io/apis/querator-api/changes/v1/queue.reserve/post.md)

---

[API](https://skmtc.dev/kapetan-io/apis/querator-api.md) · [All operations](https://skmtc.dev/kapetan-io/apis/querator-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kapetan-io/querator-api/revisions/36fb0df413ee/schema)