Bulk Operations

Perform batch create, update, or delete operations in a single request. Bulk endpoints process each item independently — individual failures don't prevent other items from succeeding.

Endpoints

Method	Endpoint	Description
POST	/{entity}/bulk	Create multiple records
PUT	/{entity}/bulk	Update multiple records
DELETE	/{entity}/bulk	Delete multiple records

Batch Limits

• Maximum batch size: 100 items per request
• Empty arrays return 400 BAD_REQUEST
• Arrays exceeding 100 items return 400 BAD_REQUEST

Bulk Create

Create multiple records at once. Each item is validated and persisted independently.

Request:

curl -X POST ".../api/v1/acme-corp/sales/customers/bulk" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" },
    { "name": "Charlie", "email": "charlie@example.com" }
  ]'

Response (200):

{
  "succeeded": 3,
  "failed": 0
}

Bulk Update

Update multiple records. Each item must include the primary key field (id).

Request:

curl -X PUT ".../api/v1/acme-corp/sales/customers/bulk" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 1, "name": "Alice Updated" },
    { "id": 2, "email": "bob-new@example.com" }
  ]'

Response (200):

{
  "succeeded": 2,
  "failed": 0
}

Bulk Delete

Delete multiple records by ID.

Request:

curl -X DELETE ".../api/v1/acme-corp/sales/customers/bulk" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '[1, 2, 3]'

Response (200):

{
  "succeeded": 3,
  "failed": 0
}

Partial Success

Bulk operations always return 200 OK, even when some items fail. The response reports how many succeeded and failed, with per-item error details.

Example — 1 of 3 items fails validation:

curl -X POST ".../api/v1/acme-corp/sales/customers/bulk" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Alice", "email": "alice@example.com" },
    { "email": "missing-name@example.com" },
    { "name": "Charlie" }
  ]'

Response (200):

{
  "succeeded": 2,
  "failed": 1,
  "errors": [
    {
      "index": 1,
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Validation failed: 1 error(s)",
        "details": [{ "field": "name", "message": "name is required" }]
      }
    }
  ]
}

Per-Item Error Codes

Each failed item includes an error with one of these codes:

Code	Description
VALIDATION_ERROR	Field validation failed (with details array)
NOT_FOUND	Record with given ID not found (update/delete)
UNIQUE_CONSTRAINT_VIOLATION	Duplicate value for a unique column
BAD_REQUEST	Missing primary key or other request issue
INTERNAL_ERROR	Unexpected database error

Error Responses (Non-Partial)

These errors return standard error responses (not the bulk format):

Status	When
400	Empty array or batch size exceeds 100
401	Missing or invalid API key
403	Read-only API key or wrong workspace
404	Entity not found