Skip to main content
DELETE
Batch Delete Documents

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 header returns 403; an invalid or revoked key returns 401.

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

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:
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).

Example:
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

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).

message
string
default:Batch delete completed

Summary message of the operation