Batch Delete Documents

Batch delete multiple documents by explicit IDs or filters.

Supports TWO modes:

1. Explicit IDs mode: Provide ‘document_ids’ array

   • Deletes specific documents by ID
   • Returns detailed per-document results
   • Maximum 1000 documents per batch

2. Filter mode: Provide ‘filters’ to delete all matching documents

   • Deletes ALL documents matching the filters
   • Returns total count only
   • Use with caution - can delete many documents

Key Features:

• Per-document success/failure reporting in explicit mode
• Validates documents exist in the specified collection
• Automatic document count update for the collection
• Efficient bulk deletion

Examples: Explicit IDs mode:

{
    "document_ids": ["doc_123", "doc_456", "doc_789"]
}

Filter mode (logical AND/OR/NOT shape — NOT MVS-native must/key):

{
    "filters": {"AND": [{"field": "metadata.status", "operator": "eq", "value": "archived"}]}
}

DELETE /v1/collections/{collection_identifier}/documents/batch

Batch Delete Documents

cURL

curl --request DELETE \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Explicit IDs mode: Delete 3 specific documents",
  "document_ids": [
    "doc_123",
    "doc_456",
    "doc_789"
  ]
}
'

200

{
  "deleted_count": 3,
  "failed_count": 0,
  "message": "Successfully deleted 3 document(s)",
  "results": [
    {
      "document_id": "doc_123",
      "success": true
    },
    {
      "document_id": "doc_456",
      "success": true
    },
    {
      "document_id": "doc_789",
      "success": true
    }
  ]
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

collection_identifier · string · required

The ID of the collection to delete documents from.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for batch deleting multiple documents by explicit IDs or filters.

Supports TWO modes:

1. Explicit IDs mode: Provide 'document_ids' array
2. Filter mode: Provide 'filters' to delete all matching documents

Use Cases: - Delete 5 specific documents in one API call - Delete all documents matching criteria - Bulk cleanup operations

Requirements: - EITHER 'document_ids' OR 'filters' must be provided - NOT BOTH modes simultaneously

document_ids · string[] | null

OPTIONAL. List of document IDs to delete. Use this mode when you know exact document IDs to delete. Mutually exclusive with filters mode. Maximum 1000 documents per batch request.

Required array length: 1 - 1000 elements

Example:

["doc_123", "doc_456", "doc_789"]

filters · LogicalOperator · object | null

OPTIONAL. Filter conditions to match documents for deletion. Mutually exclusive with 'document_ids' array. If provided, deletes ALL documents matching the filters. Use with caution - can delete many documents at once. Uses the logical AND/OR/NOT shape (not MVS-native must/key).

Show child attributes

Example:

{
  "AND": [
    {
      "field": "metadata.status",
      "operator": "eq",
      "value": "archived"
    }
  ]
}

reason · string | null

OPTIONAL. Why this bulk delete is happening — recorded on the DOCUMENT_BULK_SOFT_DELETED audit event so a document-level wipe carries the caller's own context, not just the actor and counts.

Maximum string length: 500

Example:

"retention policy cleanup"

Response

200

application/json

Successful Response

Response model for batch document delete operation.

Two shapes, keyed on the request mode:

• Explicit IDs mode is SYNCHRONOUS and fast (targets point ids directly): deleted_count / failed_count / results are populated, task_id is null.
• Filter mode is ASYNC: it scrolls matches on the shard, which can exceed a request's connection window (same cost shape as bulk update), so it enqueues a task and returns task_id + status=PENDING with deleted_count null. Poll GET /v1/tasks/{task_id} for the terminal status and deleted_count.

task_id · string | null

Id of the background task for a FILTER-mode delete. Null for explicit-IDs mode (which completes synchronously). Poll GET /v1/tasks/{task_id} for status and the final deleted_count.

status · string | null

Task status at enqueue time (PENDING) for a filter-mode delete. Null for the synchronous explicit-IDs mode.

deleted_count · integer | null

Total number of documents successfully deleted. Null on the async filter-mode enqueue response; populated on the task record when it completes, and returned synchronously in explicit-IDs mode.

failed_count · integer · default: 0

Total number of documents that failed to delete

results · BatchDocumentDeleteResult · object[]

Detailed per-document results. Each entry shows document_id, success status, and error message (if failed). Empty list when using filter mode (only counts returned).

Show child attributes

limits · Limits · object | null

Filter mode only: the caps this request ran against. max_rows_inline is the row cap under which a delete by filter runs in the request; matched is how many documents the filter matched when the request arrived. Over the cap the delete runs as a task (task_id).

Show child attributes

Example:

{ "matched": 5000, "max_rows_inline": 10000 }

message · string · default: Batch delete completed

Summary message of the operation