Skip to main content
POST
/
{collection}
/
batch
Batch Create
curl --request POST \
  --url https://api.example.com/{collection}/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {}
  ]
}
'
{
  "created": [
    {}
  ],
  "failed": [
    {
      "index": 123,
      "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Overview

The batch create endpoint allows you to insert multiple documents into a collection in a single atomic operation. Each document is validated against the collection schema, and pre/post-create hooks are executed for each document.

Request

collection
string
required
The name of the collection to insert documents into
documents
array
required
Array of documents to create. Each document is a JSON object with field values matching the collection schema.Maximum batch size: 1000 documents (configurable)

Request Example

{
  "documents": [
    {
      "name": "Alice Johnson",
      "email": "[email protected]",
      "role": "manager",
      "department": "Engineering"
    },
    {
      "name": "Bob Smith",
      "email": "[email protected]",
      "role": "developer",
      "department": "Engineering"
    },
    {
      "name": "Carol White",
      "email": "[email protected]",
      "role": "designer",
      "department": "Product"
    }
  ]
}

Response

created
array
Array of document IDs that were successfully created
failed
array
Array of failures with index and error details for documents that could not be created
index
integer
The index of the failed document in the original request array
error
object
Error details
code
string
Error code (e.g., schema_validation, bad_request)
message
string
Human-readable error message

Response Example

{
  "created": [
    "65f1a2b3c4d5e6f7a8b9c0d1",
    "65f1a2b3c4d5e6f7a8b9c0d2"
  ],
  "failed": [
    {
      "index": 2,
      "error": {
        "code": "schema_validation",
        "message": "Field 'email' is required"
      }
    }
  ]
}

Batch Processing Details

Automatic Fields

Each document automatically receives:
  • created_by: Set to the authenticated user’s ID
  • created_at: Set to current UTC timestamp
  • updated_at: Set to current UTC timestamp
  • Tenant/owner fields (if configured in collection schema)

Validation

  1. Schema Validation: Each document is validated against the collection schema
  2. Permission Check: User must have create permission for the collection
  3. Batch Size Limit: Maximum 1000 documents per request (default, configurable)
  4. Pre-create Hooks: Executed for each valid document before insertion

Partial Success

Batch create supports partial success:
  • Documents that pass validation are inserted
  • Documents that fail validation are returned in the failed array
  • The operation does not roll back on partial failures

Hook Execution

From handlers_batch.go:212-284:
  • Pre-create hooks are executed for each document before insertion
  • If a pre-create hook fails, that document is not inserted
  • Post-create hooks are executed after successful insertion (best-effort)
  • Hook failures do not affect other documents in the batch

Error Responses

error
object
code
string
Error code:
  • collection_not_found: Collection does not exist
  • forbidden: User lacks create permission
  • bad_request: Invalid request format or batch size exceeded
  • schema_validation: One or more documents failed validation
message
string
Human-readable error message
details
object
Additional error context (batch size, validation errors, etc.)

Error Example

{
  "error": {
    "code": "bad_request",
    "message": "Batch size exceeds maximum limit of 1000",
    "details": {
      "max_batch_size": 1000,
      "requested": 1500
    }
  }
}

Code Reference

Implementation: pkg/api/handlers_batch.go:113-300

Build docs developers (and LLMs) love