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

Get started for freeTalk to us