Batch Update Documents
curl --request POST \
--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: Update 3 documents with different values",
"updates": [
{
"document_id": "doc_frame_001",
"update_data": {
"metadata.quality_score": 0.95,
"metadata.reviewed": true
}
},
{
"document_id": "doc_frame_002",
"update_data": {
"metadata.flagged": true,
"metadata.quality_score": 0.87
}
},
{
"document_id": "doc_frame_003",
"update_data": {
"metadata.discarded": true,
"metadata.quality_score": 0.72
}
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload = {
"description": "Explicit IDs mode: Update 3 documents with different values",
"updates": [
{
"document_id": "doc_frame_001",
"update_data": {
"metadata.quality_score": 0.95,
"metadata.reviewed": True
}
},
{
"document_id": "doc_frame_002",
"update_data": {
"metadata.flagged": True,
"metadata.quality_score": 0.87
}
},
{
"document_id": "doc_frame_003",
"update_data": {
"metadata.discarded": True,
"metadata.quality_score": 0.72
}
}
]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Explicit IDs mode: Update 3 documents with different values',
updates: [
{
document_id: 'doc_frame_001',
update_data: {'metadata.quality_score': 0.95, 'metadata.reviewed': true}
},
{
document_id: 'doc_frame_002',
update_data: {'metadata.flagged': true, 'metadata.quality_score': 0.87}
},
{
document_id: 'doc_frame_003',
update_data: {'metadata.discarded': true, 'metadata.quality_score': 0.72}
}
]
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Explicit IDs mode: Update 3 documents with different values',
'updates' => [
[
'document_id' => 'doc_frame_001',
'update_data' => [
'metadata.quality_score' => 0.95,
'metadata.reviewed' => true
]
],
[
'document_id' => 'doc_frame_002',
'update_data' => [
'metadata.flagged' => true,
'metadata.quality_score' => 0.87
]
],
[
'document_id' => 'doc_frame_003',
'update_data' => [
'metadata.discarded' => true,
'metadata.quality_score' => 0.72
]
]
]
]),
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: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("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: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\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::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Explicit IDs mode: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"failed_count": 0,
"message": "Successfully updated 3 document(s)",
"results": [
{
"document_id": "doc_123",
"success": true
},
{
"document_id": "doc_456",
"success": true
},
{
"document_id": "doc_789",
"success": true
}
],
"updated_count": 3
}{
"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
}{
"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
}Documents
Batch Update Documents
Batch update multiple documents by explicit IDs or filters.
Supports TWO modes:
-
Explicit IDs mode: Provide ‘updates’ array with document_id + update_data for each document
- Each document can have DIFFERENT update_data
- Returns detailed per-document results
-
Filter mode: Provide ‘filters’ + ‘update_data’ to update all matching documents
- All documents receive the SAME update_data
- Returns total count only
Key Features:
- Update any document field except vectors (metadata, internal_metadata, source_blobs, etc.)
- Maximum 1000 documents per batch in explicit mode
- Per-document success/failure reporting in explicit mode
- Validates documents exist in the specified collection
Examples: Explicit IDs mode:
{
"updates": [
{"document_id": "doc_123", "update_data": {"metadata": {"status": "processed"}}},
{"document_id": "doc_456", "update_data": {"metadata": {"status": "archived"}}}
]
}
Filter mode (logical AND/OR/NOT shape — NOT MVS-native must/key):
{
"filters": {"AND": [{"field": "metadata.status", "operator": "eq", "value": "pending"}]},
"update_data": {"metadata": {"status": "processed"}}
}
POST
/
v1
/
collections
/
{collection_identifier}
/
documents
/
batch
Batch Update Documents
curl --request POST \
--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: Update 3 documents with different values",
"updates": [
{
"document_id": "doc_frame_001",
"update_data": {
"metadata.quality_score": 0.95,
"metadata.reviewed": true
}
},
{
"document_id": "doc_frame_002",
"update_data": {
"metadata.flagged": true,
"metadata.quality_score": 0.87
}
},
{
"document_id": "doc_frame_003",
"update_data": {
"metadata.discarded": true,
"metadata.quality_score": 0.72
}
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/batch"
payload = {
"description": "Explicit IDs mode: Update 3 documents with different values",
"updates": [
{
"document_id": "doc_frame_001",
"update_data": {
"metadata.quality_score": 0.95,
"metadata.reviewed": True
}
},
{
"document_id": "doc_frame_002",
"update_data": {
"metadata.flagged": True,
"metadata.quality_score": 0.87
}
},
{
"document_id": "doc_frame_003",
"update_data": {
"metadata.discarded": True,
"metadata.quality_score": 0.72
}
}
]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Explicit IDs mode: Update 3 documents with different values',
updates: [
{
document_id: 'doc_frame_001',
update_data: {'metadata.quality_score': 0.95, 'metadata.reviewed': true}
},
{
document_id: 'doc_frame_002',
update_data: {'metadata.flagged': true, 'metadata.quality_score': 0.87}
},
{
document_id: 'doc_frame_003',
update_data: {'metadata.discarded': true, 'metadata.quality_score': 0.72}
}
]
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Explicit IDs mode: Update 3 documents with different values',
'updates' => [
[
'document_id' => 'doc_frame_001',
'update_data' => [
'metadata.quality_score' => 0.95,
'metadata.reviewed' => true
]
],
[
'document_id' => 'doc_frame_002',
'update_data' => [
'metadata.flagged' => true,
'metadata.quality_score' => 0.87
]
],
[
'document_id' => 'doc_frame_003',
'update_data' => [
'metadata.discarded' => true,
'metadata.quality_score' => 0.72
]
]
]
]),
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: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("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: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\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::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Explicit IDs mode: Update 3 documents with different values\",\n \"updates\": [\n {\n \"document_id\": \"doc_frame_001\",\n \"update_data\": {\n \"metadata.quality_score\": 0.95,\n \"metadata.reviewed\": true\n }\n },\n {\n \"document_id\": \"doc_frame_002\",\n \"update_data\": {\n \"metadata.flagged\": true,\n \"metadata.quality_score\": 0.87\n }\n },\n {\n \"document_id\": \"doc_frame_003\",\n \"update_data\": {\n \"metadata.discarded\": true,\n \"metadata.quality_score\": 0.72\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"failed_count": 0,
"message": "Successfully updated 3 document(s)",
"results": [
{
"document_id": "doc_123",
"success": true
},
{
"document_id": "doc_456",
"success": true
},
{
"document_id": "doc_789",
"success": true
}
],
"updated_count": 3
}{
"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
}{
"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
}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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.
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 update documents in.
Body
application/json
Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.
Request model for batch updating multiple documents by explicit IDs or filters.
Supports TWO modes:
- Explicit IDs mode: Provide 'updates' array with document_id + update_data for each
- Filter mode: Provide 'filters' + 'update_data' to update all matching documents
Key difference from BulkUpdateDocumentsRequest:
- Batch (this): Can apply DIFFERENT updates to SPECIFIC documents by ID
- Bulk: Applies SAME update to ALL documents matching filters
Use Cases: - Update 5 specific documents with different metadata values - Update documents by IDs with per-document update control - Combine with filters for targeted batch updates
Requirements: - EITHER 'updates' (explicit mode) OR 'filters' + 'update_data' (filter mode) - NOT BOTH modes simultaneously
OPTIONAL. List of document updates with explicit document IDs. Each entry specifies document_id and update_data. Use this mode when you know exact document IDs and want per-document control. Mutually exclusive with filters + update_data mode. Maximum 1000 documents per batch request.
Required array length:
1 - 1000 elementsShow child attributes
Show child attributes
Example:
[
{
"document_id": "doc_123",
"update_data": { "metadata.status": "processed" }
},
{
"document_id": "doc_456",
"update_data": { "metadata.status": "archived" }
}
]
OPTIONAL. Filter conditions to match documents for update. Must be used with 'update_data' field. Mutually exclusive with 'updates' array. If provided, applies same update_data to all matching documents.
Show child attributes
Show child attributes
OPTIONAL. Update data to apply when using filters mode. Must be used with 'filters' field. All matched documents receive the same updates. Can update any document field except vectors. A dotted key sets one nested field and keeps its siblings: {'metadata.status': 'processed'} changes only metadata.status. A key without a dot replaces that whole top-level field, so {'metadata': {'status': 'processed'}} replaces the entire metadata object and drops its other keys.
Response
Successful Response
Response model for batch document update operation.
Provides detailed per-document results showing success/failure for each update.
Total number of documents successfully updated
Total number of documents that failed to update
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?