Skip to main content
DELETE
/
v1
/
collections
/
{collection_identifier}
/
documents
/
batch
Batch Delete Documents
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: <x-namespace>' \
  --data '{
  "description": "Explicit IDs mode: Delete 3 specific documents",
  "document_ids": [
    "doc_123",
    "doc_456",
    "doc_789"
  ]
}'
{
  "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

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

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
Examples:
["doc_123", "doc_456", "doc_789"]
["doc_frame_001", "doc_frame_002"]
​
filters
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. 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"}).

Examples:
{
  "must": [
    {
      "key": "metadata.status",
      "value": "archived"
    }
  ]
}

Response

Successful Response

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