Batch API reference

The Batch API accepts several record operations in one request. PocketBase validates the whole batch against the configured maximum, processes supported operations in a transaction, and returns each operation's status and body. Batch requests are disabled unless an administrator enables them and sets a positive maximum.

POST /api/batch

The endpoint accepts JSON or multipart form data. The JSON request contains a required requests array. Each item has a method, URL, and optional body and headers. The supported record actions are POST, PATCH, and DELETE on Records API routes, plus PUT for record upsert.

curl --request POST \
  --url http://127.0.0.1:8090/api/batch \
  --header 'Content-Type: application/json' \
  --data '{
  "requests": [],
  "requests[].method": "<string>",
  "requests[].url": "<string>",
  "requests[].body": {},
  "requests[].headers": {}
}'

{ "status": 200, "data": { "responses": [ { "status": 200, "body": {} } ] } }

curl -X POST 'http://127.0.0.1:8090/api/batch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: RECORD_TOKEN' \
  --data '{"requests":[{"method":"POST","url":"/api/collections/tasks/records","body":{"title":"Write docs"}},{"method":"PATCH","url":"/api/collections/tasks/records/RECORD_ID","body":{"done":true}}]}'

The response contains a result for each operation with status and body. A failed operation produces a batch failure response and the transaction does not represent a successful all-or-nothing completion; inspect the reported failed index and response before retrying.

Limits and interruption

The configured Batch.MaxRequests limits the number of array items. Batch.MaxBodySize limits the request body. A batch transaction uses Batch.Timeout seconds; when that value is not positive, the current implementation applies a three-second timeout. A timed-out transaction returns the batch transaction timeout error. If the client request context ends, processing stops with batch request interrupted.

Multipart requests serialize regular fields as JSON under @jsonPayload. File keys use requests.N.fileField or requests[N].fileField. Keep the batch within the configured body size and request count; split work into smaller batches when either limit is reached.

Unsupported actions and recovery

Routes outside the supported batch action set, such as /api/health, fail with unknown batch request action. A validation error prevents processing. Correct the method, URL, body, or configured limit, then submit a new batch. Do not blindly retry a request after an ambiguous timeout if an operation may have reached the database; query the affected records first.

Continue with Records API reference for individual operation schemas and API rules and filters for authorization behavior.