queues - Korve

Multi-tenant project queues with isolated names, signed push consumers, delayed delivery, retries, and dead-letter handling. Delivery is at least once and unordered.

queues.list

List queues in one project environment.

GET /v1/orgs/{orgId}/projects/{projectId}/queues

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Queues ordered by name.
`404`	No such project or environment in this organization.

Response body (200)

An array of objects with these fields:

Field	Type	Description
`id`	string	—
`name`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`environment`	string	—
`status`	string	One of: `provisioning`, `ready`, `paused`, `failed`.
`retentionSeconds`	integer	Message retention. Configurable up to 14 days.
`deliveryDelaySeconds`	integer	Default delivery delay, at most 86400 seconds.
`deadLetterQueueId`	string or null	—
`consumer`	object	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.
`deliveryGuarantee`	string	One of: `at-least-once`.
`orderingGuarantee`	string	One of: `none`.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

queues.create

Create an isolated queue with an authenticated signed push consumer. Customer message bodies are limited to 122,880 bytes and encoded envelopes to 128,000 bytes. Messages are at-least-once, unordered, retained for at most 14 days, and may be delayed up to 24 hours.

POST /v1/orgs/{orgId}/projects/{projectId}/queues

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`name`	string	Yes	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`retentionSeconds`	integer	No	Retention from 60 seconds through 14 days. Defaults to four days.
`deliveryDelaySeconds`	integer	No	Default delay from 0 through 86400 seconds.
`deadLetterQueueId`	string or null	No	—
`consumer`	object	Yes	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Yes	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	No	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	No	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	No	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	No	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	No	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "consumer": {
    "path": "/health"
  }
}'

Responses

Status	Description
`201`	Queue provisioning started.
`404`	No such project, environment, or dead-letter queue.
`409`	A queue with that name already exists in the environment.
`422`	Invalid queue or consumer configuration.

Response body (201)

Field	Type	Description
`id`	string	—
`name`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`environment`	string	—
`status`	string	One of: `provisioning`, `ready`, `paused`, `failed`.
`retentionSeconds`	integer	Message retention. Configurable up to 14 days.
`deliveryDelaySeconds`	integer	Default delivery delay, at most 86400 seconds.
`deadLetterQueueId`	string or null	—
`consumer`	object	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.
`deliveryGuarantee`	string	One of: `at-least-once`.
`orderingGuarantee`	string	One of: `none`.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

queues.get

Get a queue and its delivery configuration.

GET /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Queue configuration.
`404`	No such queue in this project.

Response body (200)

Field	Type	Description
`id`	string	—
`name`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`environment`	string	—
`status`	string	One of: `provisioning`, `ready`, `paused`, `failed`.
`retentionSeconds`	integer	Message retention. Configurable up to 14 days.
`deliveryDelaySeconds`	integer	Default delivery delay, at most 86400 seconds.
`deadLetterQueueId`	string or null	—
`consumer`	object	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.
`deliveryGuarantee`	string	One of: `at-least-once`.
`orderingGuarantee`	string	One of: `none`.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

queues.update

Update retention, delivery delay, consumer, pause state, or dead-letter routing.

PATCH /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`retentionSeconds`	integer	No	—
`deliveryDelaySeconds`	integer	No	—
`deadLetterQueueId`	string or null	No	—
`consumer`	object	No	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Yes	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	No	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	No	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	No	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	No	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	No	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.
`paused`	boolean	No	—

Example

curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`200`	Updated queue.
`404`	No such queue in this project.
`422`	Invalid queue configuration.

Response body (200)

Field	Type	Description
`id`	string	—
`name`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`environment`	string	—
`status`	string	One of: `provisioning`, `ready`, `paused`, `failed`.
`retentionSeconds`	integer	Message retention. Configurable up to 14 days.
`deliveryDelaySeconds`	integer	Default delivery delay, at most 86400 seconds.
`deadLetterQueueId`	string or null	—
`consumer`	object	Signed push consumer. A delivery invokes this project-relative HTTPS path with one message envelope or `{ messages: [...] }` for a logical batch. Deliveries are at least once; a successful 2xx response acknowledges every message in that request.
`consumer.path`	string	Project-relative HTTP path. Absolute URLs and cross-project delivery are refused. Pattern: `^/`.
`consumer.maxBatchSize`	integer	Maximum messages in one signed consumer request, from 1 to 100.
`consumer.maxBatchWaitSeconds`	integer	Maximum time an underfilled logical batch may wait after its first message becomes available, from 0 to 60 seconds.
`consumer.maxRetries`	integer	Delivery retries, from 0 to 100. Defaults to 3.
`consumer.retryDelaySeconds`	integer	Delay before retry, from 0 to 86400 seconds.
`consumer.maxConcurrency`	integer or null	Maximum concurrent signed batch requests for this logical queue across all platform replicas; null lets the platform scale automatically.
`deliveryGuarantee`	string	One of: `at-least-once`.
`orderingGuarantee`	string	One of: `none`.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

queues.delete

Delete a queue and all queued and dead-letter messages. This cannot be undone.

DELETE /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: owner
Risk: destructive · sensitive (elevated blast radius)

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Queue deleted.
`404`	No such queue in this project.
`409`	Another queue still routes dead letters here.

queues.publish

Publish one message. A successful response durably accepts it for at-least-once delivery.

POST /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/messages

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`body`	object	Yes	JSON message body may not exceed 122,880 bytes; the complete encoded message may not exceed 128,000 bytes.
`contentType`	string	No	Application media type. Defaults to application/json.
`delaySeconds`	integer	No	Per-message delay, from 0 to 86400 seconds.
`idempotencyKey`	string	No	Caller key for safely retrying publication without creating another message.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/messages" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "body": {}
}'

Responses

Status	Description
`202`	Message accepted.
`404`	No such queue in this project.
`409`	Queue is not accepting messages in its current state.
`413`	Customer body exceeds 122,880 bytes or its encoded envelope exceeds 128,000 bytes.
`422`	Invalid message or delay.
`429`	Queue throughput or capacity limit reached.

Response body (202)

Field	Type	Description
`messageId`	string	—
`acceptedAt`	string	Format: `date-time`.

queues.publishBatch

Publish up to 100 messages in one request of at most 256,000 encoded bytes; each accepted message is delivered independently.

POST /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/messages/batch

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`messages`	object[]	Yes	—
`messages[].body`	object	Yes	JSON message body may not exceed 122,880 bytes; the complete encoded message may not exceed 128,000 bytes.
`messages[].contentType`	string	No	Application media type. Defaults to application/json.
`messages[].delaySeconds`	integer	No	Per-message delay, from 0 to 86400 seconds.
`messages[].idempotencyKey`	string	No	Caller key for safely retrying publication without creating another message.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/messages/batch" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "body": {}
    }
  ]
}'

Responses

Status	Description
`202`	Messages accepted in input order.
`404`	No such queue in this project.
`409`	Queue is not accepting messages in its current state.
`413`	A customer body exceeds 122,880 bytes, an encoded envelope exceeds 128,000 bytes, or the encoded batch exceeds 256,000 bytes.
`422`	Batch is empty, too large, or invalid.
`429`	Queue throughput or capacity limit reached.

Response body (202)

An array of objects with these fields:

Field	Type	Description
`messageId`	string	—
`acceptedAt`	string	Format: `date-time`.

queues.stats

Get backlog, throughput, delivery, retry, and dead-letter counters for a time window.

GET /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/stats

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`since`	string	No	Format: `date-time`.
`until`	string	No	Format: `date-time`.

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/stats?since=2026-06-01T12%3A00%3A00Z" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Queue statistics.
`404`	No such queue in this project.
`422`	Invalid time window.

Response body (200)

Field	Type	Description
`sampledAt`	string	Format: `date-time`.
`backlogMessages`	integer	—
`backlogBytes`	integer	—
`published`	integer	—
`delivered`	integer	—
`retried`	integer	—
`deadLettered`	integer	—
`oldestMessageAgeSeconds`	integer or null	—

queues.listDeadLetters

Page messages that exhausted delivery retries.

GET /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/dead-letters

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/dead-letters?cursor=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Dead-letter page.
`404`	No such queue in this project.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].messageId`	string	—
`items[].body`	object	—
`items[].attempts`	integer	—
`items[].failedAt`	string	Format: `date-time`.
`items[].lastError`	string or null	—
`nextCursor`	string or null	—

queues.replayDeadLetters

Republish selected or all dead-letter messages and remove successfully accepted originals.

POST /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/dead-letters/replay

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: dangerous · sensitive (elevated blast radius)

Request body

Field	Type	Required	Description
`messageIds`	string[]	No	—
`all`	boolean	No	—

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/dead-letters/replay" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`202`	Replay accepted.
`404`	No such queue or message in this project.
`422`	Select messageIds or all, but not both.

Response body (202)

Field	Type	Description
`accepted`	integer	—

queues.purgeDeadLetters

Permanently delete every dead-letter message in this queue.

DELETE /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId}/dead-letters

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: owner
Risk: destructive · sensitive (elevated blast radius)

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/queues/$QUEUE_ID/dead-letters" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Dead letters purged.
`404`	No such queue in this project.

Response body (200)

Field	Type	Description
`deleted`	integer	—

queues.runtimeSend

Publish one message from a deployed server runtime. The injected token resolves exactly one project and environment and cannot address another tenant.

POST /v1/runtime/queues/{queueName}/messages

Auth: Project app-service token (Authorization: Bearer $APP_SERVICE_TOKEN).
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`body`	object	Yes	JSON message body may not exceed 122,880 bytes; the complete encoded message may not exceed 128,000 bytes.
`contentType`	string	No	Application media type. Defaults to application/json.
`delaySeconds`	integer	No	Per-message delay, from 0 to 86400 seconds.
`idempotencyKey`	string	No	Caller key for safely retrying publication without creating another message.

Example

curl -X POST "https://api.korve.dev/v1/runtime/queues/$QUEUE_NAME/messages" \
  -H "Authorization: Bearer $APP_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "body": {}
}'

Responses

Status	Description
`202`	Message accepted.
`401`	Runtime token is absent, invalid, expired, or outside this environment.
`404`	No such queue in the runtime environment.
`409`	Queue is not accepting messages in its current state.
`413`	Customer body exceeds 122,880 bytes or its encoded envelope exceeds 128,000 bytes.
`422`	Invalid message or delay.
`429`	Queue throughput or capacity limit reached.

Response body (202)

Field	Type	Description
`messageId`	string	—
`acceptedAt`	string	Format: `date-time`.

queues.runtimeSendBatch

Publish up to 100 messages in one request of at most 256,000 encoded bytes from a deployed server runtime using its project-and-environment-scoped token.

POST /v1/runtime/queues/{queueName}/messages/batch

Auth: Project app-service token (Authorization: Bearer $APP_SERVICE_TOKEN).
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`messages`	object[]	Yes	—
`messages[].body`	object	Yes	JSON message body may not exceed 122,880 bytes; the complete encoded message may not exceed 128,000 bytes.
`messages[].contentType`	string	No	Application media type. Defaults to application/json.
`messages[].delaySeconds`	integer	No	Per-message delay, from 0 to 86400 seconds.
`messages[].idempotencyKey`	string	No	Caller key for safely retrying publication without creating another message.

Example

curl -X POST "https://api.korve.dev/v1/runtime/queues/$QUEUE_NAME/messages/batch" \
  -H "Authorization: Bearer $APP_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "body": {}
    }
  ]
}'

Responses

Status	Description
`202`	Messages accepted in input order.
`401`	Runtime token is absent, invalid, expired, or outside this environment.
`404`	No such queue in the runtime environment.
`409`	Queue is not accepting messages in its current state.
`413`	A customer body exceeds 122,880 bytes, an encoded envelope exceeds 128,000 bytes, or the encoded batch exceeds 256,000 bytes.
`422`	Batch is empty, too large, or invalid.
`429`	Queue throughput or capacity limit reached.

Response body (202)

An array of objects with these fields:

Field	Type	Description
`messageId`	string	—
`acceptedAt`	string	Format: `date-time`.

​queues.list

​Query parameters

​Example

​Responses

​Response body (200)

​queues.create

​Query parameters

​Request body

​Example

​Responses

​Response body (201)

​queues.get

​Example

​Responses

​Response body (200)

​queues.update

​Request body

​Example

​Responses

​Response body (200)

​queues.delete

​Example

​Responses

​queues.publish

​Request body

​Example

​Responses

​Response body (202)

​queues.publishBatch

​Request body

​Example

​Responses

​Response body (202)

​queues.stats

​Query parameters

​Example

​Responses

​Response body (200)

​queues.listDeadLetters

​Query parameters

​Example

​Responses

​Response body (200)

​queues.replayDeadLetters

​Request body

​Example

​Responses

​Response body (202)

​queues.purgeDeadLetters

​Example

​Responses

​Response body (200)

​queues.runtimeSend

​Request body

​Example

​Responses

​Response body (202)

​queues.runtimeSendBatch

​Request body

​Example

​Responses

​Response body (202)

queues.list

Query parameters

Example

Responses

Response body (200)

queues.create

Query parameters

Request body

Example

Responses

Response body (201)

queues.get

Example

Responses

Response body (200)

queues.update

Request body

Example

Responses

Response body (200)

queues.delete

Example

Responses

queues.publish

Request body

Example

Responses

Response body (202)

queues.publishBatch

Request body

Example

Responses

Response body (202)

queues.stats

Query parameters

Example

Responses

Response body (200)

queues.listDeadLetters

Query parameters

Example

Responses

Response body (200)

queues.replayDeadLetters

Request body

Example

Responses

Response body (202)

queues.purgeDeadLetters

Example

Responses

Response body (200)

queues.runtimeSend

Request body

Example

Responses

Response body (202)

queues.runtimeSendBatch

Request body

Example

Responses

Response body (202)