> ## Documentation Index > Fetch the complete documentation index at: https://docs.korve.dev/llms.txt > Use this file to discover all available pages before exploring further. # queues > Multi-tenant project queues with isolated names, signed push consumers, delayed delivery, retries, and dead-letter handling. Delivery is at least once and unordered. 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} GET /v1/orgs/{orgId}/projects/{projectId}/queues/{queueId} ``` * **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session. * **Minimum role:** `member` * **Risk:** `read` ### Example ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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`. |