API Reference

Authorization: Bearer

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

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.

Common headers

The following headers are used across multiple endpoints:

Region routing

Deployment ID for per-deployment isolation. When omitted, requests operate in deploymentless mode

Type

Required

Bearer

Header

Authorization

Vqs-Deployment-Id

-

Description

string

-

Naming constraints

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

Default

Yes

No

string

Endpoints

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

POST /api/v3/topic/{topic}

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 https://fra1.vercel-queue.com/api/v3/topic/orders

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

Type

MIME type of the message payload. Preserved and returned to consumers

Vqs-Delay-Seconds

Message TTL. Minimum 60 seconds, maximum 7 days (604,800 seconds)

Description

Required

No

Default

Vqs-Retention-Seconds

Deduplication key. Duplicate messages are silently dropped out-of-band

string

Content-Type

integer

No

Vqs-Idempotency-Key

Delay before message becomes visible. Maximum 7 days (604,800 seconds), capped at message TTL

24 hours

integer

Zero seconds

string

Request body

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

Response

A 201 Created response means the message was stored and delivered to consumers:

{

"messageId":"msg_abc123..."

}

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

A 202 Accepted response means the message was 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

}

Idempotency

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.

Error responses

Status

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

Invalid topic name, retention, or delay value

400

Description

Missing or invalid authentication token

429

ReceiveMessages

Request headers

401

Rate limited

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.

Header

Maximum messages to return. Min: 1, max: 10

Accept

Response format: multipart/mixed or application/x-ndjson

Type

Required

Yes

Default

Vqs-Max-Messages

Vqs-Visibility-Timeout-Seconds

string

Description

60 seconds

No

Vqs-Max-Concurrency

Maximum messages in-flight simultaneously for this consumer group. Returns 429 when exceeded

integer

Unlimited

Response formats

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:

Header

Number of times this message has been delivered (starts at 1)

Content-Type

Vqs-Message-Id

Original MIME type of the message payload

string

Unique message identifier

string

Vqs-Receipt-Handle

Vqs-Delivery-Count

Description

string

Type

integer

Vqs-Timestamp

Vqs-Expires-At

string

ISO 8601 timestamp of when the message was sent

ISO 8601 timestamp of when the message expires

string

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"

messageId

Opaque handle for acknowledging or extending the lease

receiptHandle

ISO 8601 timestamp of when the message was sent

Field

string

Unique message identifier

string

deliveryCount

timestamp

Type

Description

integer

string

expiresAt

contentType

string

body

string

Status

204 No Content is returned when no messages are available.

Error responses

401

Description

Concurrency limit exceeded or rate limited

400

Missing or unsupported Accept header, invalid parameters

Missing or invalid authentication token

429

ReceiveMessageById

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

Header

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

Accept

Response format: multipart/mixed or application/x-ndjson

Type

Required

Yes

Default

Vqs-Visibility-Timeout-Seconds

Maximum concurrent in-flight messages for this consumer group

string

Description

60 seconds

No

Vqs-Max-Concurrency

Lease duration. Minimum zero seconds, maximum 60 minutes (3,600 seconds)

integer

No

Unlimited

Description

Status

400 Invalid parameters or topic name

401 Missing or invalid authentication token

404 Message not found

409 Message locked by another consumer, or duplicate message (returns originalMessageId)

410 Message already acknowledged

429 Concurrency limit exceeded or rate limited

AcknowledgeMessage

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.

Request body

None.

Response

204 No Content

Error responses

Description

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

400 Invalid topic name or receipt handle format

401 Missing or invalid authentication token

404 Message not found or already acknowledged

409 Lease expired or receipt handle mismatch

429 Rate limited

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

Request body

The receiptHandle must be URL-encoded in the path.

{

}

"visibilityTimeoutSeconds":120

An alternate URL for the same operation is also available:

Yes

Required

Field

visibilityTimeoutSeconds

Type

integer

Description

New visibility timeout from now. Minimum zero seconds, maximum 60 minutes (3,600 seconds). Set to zero seconds to release the message immediately

200 OK

{

Response

"success":true

You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.

We’re committed to providing prompt and effective solutions to ensure your satisfaction.

}

We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.