---
title: "Batch Delete Documents"
method: DELETE
path: "/v1/collections/{collection_identifier}/documents/batch"
tags: ["Collection Documents"]
---

# Batch Delete Documents

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

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:
    ```json
    {
        "document_ids": ["doc_123", "doc_456", "doc_789"]
    }
    ```

    Filter mode (logical AND/OR/NOT shape — NOT MVS-native must/key):
    ```json
    {
        "filters": {"AND": [{"field": "metadata.status", "operator": "eq", "value": "archived"}]}
    }
    ```

## Path parameters

- `collection_identifier` string, required — The ID of the collection to delete documents from.

## Request body

- BatchDeleteDocumentsRequest — 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[], nullable — 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.
  - `filters` LogicalOperatorInput — Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).
    - `AND` union[], nullable — Logical AND operation - all conditions must be true
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `OR` union[], nullable — Logical OR operation - at least one condition must be true
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `NOT` union[], nullable — Logical NOT operation - all conditions must be false
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `case_sensitive` boolean, nullable — Whether to perform case-sensitive matching
  - `reason` string, nullable — OPTIONAL. Why this bulk delete is happening — recorded on the DOCUMENT_BULK_SOFT_DELETED audit event (BACKE-3150) so a document-level wipe carries the caller's own context, not just the actor and counts.

## Response `200`

Successful Response

- BatchDeleteDocumentsResponse — Response model for batch document delete operation. Provides detailed per-document results showing success/failure for each deletion.
  - `deleted_count` integer, required — Total number of documents successfully deleted
  - `failed_count` integer — Total number of documents that failed to delete
  - `results` BatchDocumentDeleteResult[] — 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).
    - `document_id` string, required — Document ID that was deleted
    - `success` boolean, required — Whether the deletion succeeded
    - `error` string, nullable — Error message if deletion failed
  - `message` string — Summary message of the operation

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/04b379bdbb7c/schema)