Vercel Queues API reference

The Vercel Queues API is a REST API for publishing, consuming, and managing messages. Endpoints are accessed through region-specific domains in the format https://{region}.vercel-queue.com/api/v3, where {region} is a Vercel region code (for example, iad1, fra1, sfo1).

All endpoints require a Vercel OIDC token in the Authorization header:

Authorization: Bearer <vercel-oidc-token>

The token is a JWT verified against Vercel's JWKS endpoint. It contains claims for your team, project, and environment, which are used to scope all requests.

The following headers are used across multiple endpoints:

Topic names and consumer group names must match the pattern ^[A-Za-z0-9_\-]+$ (alphanumeric characters, hyphens, and underscores only).

Each region has its own domain. Use the region code as a subdomain to route requests to a specific region:

POST https://fra1.vercel-queue.com/api/v3/topic/orders

Messages sent to one region cannot be consumed from another. For example, a message published to iad1 can only be read by consumers in iad1. See the regions documentation for the full list of available region codes.

POST /api/v3/topic/{topic}

Publishes a message to a topic. The request body is the raw message payload.

Raw binary payload. The entire request body is stored as the message content.

201 Created — Message stored and delivered to consumers:

{
  "messageId": "msg_abc123..."
}

The Vqs-Message-Id response header also contains the assigned message ID.

202 Accepted — Message stored but delivery is deferred. This happens during regional failover, when the message is temporarily stored in a neighboring region and will be relocated and delivered once the target region recovers:

{
  "deferred": true
}

When you provide Vqs-Idempotency-Key, Vercel deduplicates based on a hash of the key. Deduplication is handled out-of-band, so SendMessage always returns successfully. The duplicate message is silently dropped before it reaches any consumer. The original message continues to be delivered with at-least-once semantics.

If you use ReceiveMessageById to fetch a duplicate by its ID, the endpoint returns 409 with the originalMessageId, allowing you to follow the redirect to the original message.

The deduplication window lasts for the entire lifetime of the original message (up to its TTL), so you're protected from duplicates for the full retention period.

POST /api/v3/topic/{topic}/consumer/{consumer}

Receives available messages from the topic for the specified consumer group. Returns immediately with available messages, or 204 No Content if the topic is empty.

The Accept header controls the response format. multipart/mixed is recommended for best performance as it supports true streaming of binary payloads without encoding overhead. application/x-ndjson is provided for compatibility with clients that cannot parse multipart responses. When both formats are specified, multipart/mixed takes precedence.

multipart/mixed (recommended)

Each message is a separate MIME part with the following headers:

Example response:

--vqs-boundary-550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Vqs-Message-Id: msg_abc123...
Vqs-Receipt-Handle: rh_xyz789...
Vqs-Delivery-Count: 1
Vqs-Timestamp: 2026-01-13T12:00:00.000Z
Vqs-Expires-At: 2026-01-14T12:00:00.000Z
 
{"order": "12345", "action": "process"}
--vqs-boundary-550e8400-e29b-41d4-a716-446655440000--

application/x-ndjson (compatibility)

Provided for clients that cannot parse multipart responses. Payloads are base64-encoded, which adds overhead compared to multipart/mixed. One JSON object per line:

{"messageId":"msg_abc123...","receiptHandle":"rh_xyz789...","deliveryCount":1,"timestamp":"2026-01-13T12:00:00.000Z","expiresAt":"2026-01-14T12:00:00.000Z","contentType":"application/json","body":"eyJvcmRlciI6ICIxMjM0NSJ9"}

204 No Content is returned when no messages are available.

POST /api/v3/topic/{topic}/consumer/{consumer}/id/{messageId}

Receives a specific message by its ID and claims it for the consumer group. Useful for callback-driven processing where the message ID is known in advance.

200 OK with the same format as ReceiveMessages, containing one message.

DELETE /api/v3/topic/{topic}/consumer/{consumer}/lease/{receiptHandle}

Acknowledges successful processing of a message. The message is permanently removed from the consumer group's view.

The receiptHandle must be URL-encoded in the path.

None.

204 No Content

PATCH /api/v3/topic/{topic}/consumer/{consumer}/lease/{receiptHandle}

Extends the visibility timeout on a currently leased message. Use this to request more processing time before the lease expires.

An alternate URL for the same operation is also available:

PATCH /api/v3/topic/{topic}/consumer/{consumer}/lease/{receiptHandle}/visibility

The receiptHandle must be URL-encoded in the path.

{
  "visibilityTimeoutSeconds": 120
}

200 OK

{
  "success": true
}