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"
]
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload = {
"description": "Explicit IDs mode: Delete 3 specific documents",
"document_ids": ["doc_123", "doc_456", "doc_789"]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.delete(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'DELETE',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Explicit IDs mode: Delete 3 specific documents',
document_ids: ['doc_123', 'doc_456', 'doc_789']
})
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Explicit IDs mode: Delete 3 specific documents',
'document_ids' => [
'doc_123',
'doc_456',
'doc_789'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload := strings.NewReader("{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}")
req, _ := http.NewRequest("DELETE", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Batch Delete Documents
Batch delete multiple documents by explicit IDs or filters.
Supports TWO modes:
-
Explicit IDs mode: Provide ‘document_ids’ array
- Deletes specific documents by ID
- Returns detailed per-document results
- Maximum 1000 documents per batch
-
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"}]}
}
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"
]
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload = {
"description": "Explicit IDs mode: Delete 3 specific documents",
"document_ids": ["doc_123", "doc_456", "doc_789"]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.delete(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'DELETE',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Explicit IDs mode: Delete 3 specific documents',
document_ids: ['doc_123', 'doc_456', 'doc_789']
})
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Explicit IDs mode: Delete 3 specific documents',
'document_ids' => [
'doc_123',
'doc_456',
'doc_789'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload := strings.NewReader("{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}")
req, _ := http.NewRequest("DELETE", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Explicit IDs mode: Delete 3 specific documents\",\n \"document_ids\": [\n \"doc_123\",\n \"doc_456\",\n \"doc_789\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
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.
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
The ID of the collection to delete documents from.
Body
Request model for batch deleting multiple documents by explicit IDs or filters.
Supports TWO modes:
- Explicit IDs mode: Provide 'document_ids' array
- 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
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.
1 - 1000 elements["doc_123", "doc_456", "doc_789"]
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
Show child attributes
{
"AND": [
{
"field": "metadata.status",
"operator": "eq",
"value": "archived"
}
]
}
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.
500"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.
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.
Task status at enqueue time (PENDING) for a filter-mode delete. Null for the synchronous explicit-IDs mode.
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.
Total number of documents that failed to delete
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
Show child attributes
Summary message of the operation
Was this page helpful?

