Batch

Execute multiple API operations in a single HTTP request. Batch requests share the same authentication context (workspace and API key) as the caller.

Base URL


https://api.voxburst.io/v1/batch

Limits

Limit	Value
Max operations per batch	100
Max total request body	5 MB
Max body per individual operation	100 KB
Execution timeout	60 seconds
Allowed methods	`POST`, `PATCH`, `DELETE`

Breaking change: Individual operation bodies are now capped at 100 KB. Any batch request containing an operation whose body exceeds 100 KB is rejected with HTTP 422:


{ "error": "Operation body must not exceed 100KB" }

This limit applies per operation, independently of the 5 MB total batch limit.

Operation Schema

Each operation in the operations array has the following fields:

Field	Type	Required	Description
`id`	string	Yes	Client-assigned operation identifier (1–64 chars). Returned in results for correlation.
`method`	string	Yes	HTTP method: `POST`, `PATCH`, or `DELETE`
`path`	string	Yes	API path to call (e.g. `/v1/posts`). Max 500 chars.
`body`	object	No	Request body for the operation. Must not exceed 100 KB when serialized.
`headers`	object	No	Additional headers to pass to the operation (string key-value pairs)

Execute Batch

POST /v1/batch

Execute multiple operations sequentially (default) or in parallel.

Auth: Required

Request Body


{
  "operations": [
    {
      "id": "create-post",
      "method": "POST",
      "path": "/v1/posts",
      "body": {
        "content": "Hello from batch!",
        "accountIds": ["acc_123"]
      }
    },
    {
      "id": "delete-old",
      "method": "DELETE",
      "path": "/v1/posts/clxold1234567890"
    }
  ],
  "continueOnError": true,
  "parallel": false
}

Field	Type	Default	Description
`operations`	array	—	Operations to execute (1–100)
`continueOnError`	boolean	`true`	Continue executing remaining operations when one fails
`parallel`	boolean	`false`	Execute operations concurrently instead of sequentially

Response


{
  "results": [
    { "id": "create-post", "status": 201, "body": { "id": "clxnew...", "status": "draft" } },
    { "id": "delete-old", "status": 204, "body": null }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0, "skipped": 0 }
}

The outer response is always HTTP 200. Individual operation results carry their own HTTP status codes. A skipped operation is one that was not attempted because a prior operation failed while continueOnError was false.

Batch Transaction

POST /v1/batch/transaction

Execute operations as a fail-fast sequence. Stops on the first failure — no subsequent operations are executed.

Auth: Required

Request Body: Same schema as POST /v1/batch.

This is not a true database transaction — there is no automatic rollback of already-completed operations. Use this endpoint when you want fail-fast semantics, not when you need atomic database guarantees.

Dry Run

POST /v1/batch/dry-run

Validate a batch request without executing any operations. Checks schema, limits, and authentication, but makes no changes.

Auth: Required

Request Body: Same schema as POST /v1/batch.

Response: Same format as POST /v1/batch, with each status reflecting validation result only.

Get Limits

GET /v1/batch/limits

Returns the current batch operation limits for this workspace.

Auth: Required

Response


{
  "maxOperations": 100,
  "timeoutMs": 60000,
  "allowedMethods": ["POST", "PATCH", "DELETE"],
  "allowedPaths": [
    "/v1/posts",
    "/v1/accounts",
    "/v1/media",
    "/v1/webhooks"
  ]
}

Async Batch

POST /v1/batch/async

Submit a batch job for asynchronous processing. Returns immediately with a job ID to poll.

Auth: Required

Request Body: Same schema as POST /v1/batch.

Response


{
  "data": {
    "jobId": "clrjob1234567890abc",
    "status": "QUEUED",
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}

Get Async Job

GET /v1/batch/async/:jobId

Poll for the status and results of an async batch job.

Auth: Required

Response — while processing


{
  "data": {
    "id": "clrjob1234567890abc",
    "status": "PROCESSING",
    "results": null,
    "summary": null,
    "error": null,
    "createdAt": "2026-04-09T12:00:00.000Z",
    "startedAt": "2026-04-09T12:00:01.000Z",
    "completedAt": null
  }
}

Response — when completed


{
  "data": {
    "id": "clrjob1234567890abc",
    "status": "COMPLETED",
    "results": [
      { "id": "op1", "status": 201, "body": { "id": "clxnew..." } }
    ],
    "summary": { "total": 1, "succeeded": 1, "failed": 0, "skipped": 0 },
    "error": null,
    "createdAt": "2026-04-09T12:00:00.000Z",
    "startedAt": "2026-04-09T12:00:01.000Z",
    "completedAt": "2026-04-09T12:00:03.000Z"
  }
}

status values: QUEUED, PROCESSING, COMPLETED, FAILED. Returns 404 if the job is not found or does not belong to the calling workspace.

List Async Jobs

GET /v1/batch/async

List batch jobs for the workspace.

Auth: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1–100)
`status`	string	All	Filter by status: `QUEUED`, `PROCESSING`, `COMPLETED`, `FAILED`

Response


{
  "data": [
    {
      "id": "clrjob1234567890abc",
      "status": "COMPLETED",
      "summary": { "total": 5, "succeeded": 4, "failed": 1, "skipped": 0 },
      "error": null,
      "createdAt": "2026-04-09T12:00:00.000Z",
      "startedAt": "2026-04-09T12:00:01.000Z",
      "completedAt": "2026-04-09T12:00:05.000Z"
    }
  ]
}