Skip to main content
DELETE
/
{collection}
/
batch
Batch Delete
curl --request DELETE \
  --url https://api.example.com/{collection}/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    {}
  ],
  "filter": {}
}
'
{
  "deleted": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

​
Overview

The batch delete endpoint allows you to delete multiple documents in a single request using either an array of document IDs or a filter query. All matched documents are permanently deleted.

​
Request

​
collection
string
required
The name of the collection containing the documents to delete
​
ids
array
Array of document IDs to delete. Either ids or filter must be provided.Maximum: 1000 IDs (configurable)
​
filter
object
MongoDB-style filter query to match documents to delete. Either ids or filter must be provided.

​
Delete by IDs Example

{
  "ids": [
    "65f1a2b3c4d5e6f7a8b9c0d1",
    "65f1a2b3c4d5e6f7a8b9c0d2",
    "65f1a2b3c4d5e6f7a8b9c0d3"
  ]
}

​
Delete by Filter Example

{
  "filter": {
    "status": "archived",
    "created_at": {
      "$lt": "2023-01-01T00:00:00Z"
    }
  }
}

​
Response

​
deleted
integer
Number of documents that were successfully deleted

​
Response Example

{
  "deleted": 47
}

​
Delete Behavior

​
Permanent Deletion

Deleted documents are permanently removed from the collection. For collections with versioning enabled, a snapshot is saved before deletion.

​
Version Snapshots

From handlers_batch.go:546-556: For collections with versioning enabled, the current state of each document is saved as a version snapshot before deletion. This allows for potential recovery through the version history.

​
Hook Execution

From handlers_batch.go:559-595:
  • Pre-delete hooks: Executed for each document before deletion (best-effort in batch mode)
  • Post-delete hooks: Executed after successful deletion with the total deleted count
  • Hook failures do not prevent the deletion from proceeding

​
RBAC Filter Combination

From handlers_batch.go:541-544: The provided filter/IDs are combined with RBAC query filters to ensure users can only delete documents they have permission to access.

​
Filter Query Syntax

The filter parameter supports MongoDB query operators: 
{
  "filter": {
    "status": "archived",
    "last_login": { "$lt": "2023-01-01T00:00:00Z" },
    "email_verified": false,
    "role": { "$in": ["guest", "trial"] }
  }
}
Supported operators:
  • $eq, $ne: Equal, not equal
  • $gt, $gte, $lt, $lte: Comparison operators
  • $in, $nin: Array membership
  • $and, $or, $not: Logical operators
  • $exists: Field existence check
  • $regex: Pattern matching

​
Safety Considerations

Batch delete is a destructive operation. Deleted documents cannot be recovered unless:
  • Versioning is enabled for the collection
  • You have a backup strategy in place

​
Best Practices

  1. Test filters first: Use the Count endpoint to verify how many documents will be deleted
  2. Use specific filters: Avoid overly broad filters that might delete more than intended
  3. Enable versioning: Configure versioning for collections where you might need to recover deleted data
  4. Implement soft deletes: Consider adding a deleted field and filtering it in queries instead of hard deletes

​
Validation

  1. Permission Check: User must have delete permission for the collection
  2. Request Validation: Either ids or filter must be provided (not both)
  3. Batch Size: Maximum 1000 IDs if using ids parameter
  4. RBAC Enforcement: Only documents the user has permission to delete are affected

​
Error Responses

​
error
object
​
code
string
Error code:
  • collection_not_found: Collection does not exist
  • forbidden: User lacks delete permission
  • bad_request: Invalid request (missing ids/filter, invalid IDs, batch size exceeded)
  • internal_error: Database operation failed
​
message
string
Human-readable error message
​
details
object
Additional error context

​
Error Examples

{
  "error": {
    "code": "bad_request",
    "message": "Either 'ids' or 'filter' must be provided"
  }
}

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

​
Audit Logging

All batch delete operations are logged to the audit trail with:
  • User ID and roles
  • Collection name
  • Filter criteria or IDs
  • Number of documents deleted
  • Timestamp
From handlers_batch.go:597-602

​
Code Reference

Implementation: pkg/api/handlers_batch.go:461-610

Build docs developers (and LLMs) love

Get started for freeTalk to us