Skip to main content
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: <x-namespace>' \
  --data '{
  "description": "Explicit IDs mode: Update 3 documents with different values",
  "updates": [
    {
      "document_id": "doc_frame_001",
      "update_data": {
        "metadata": {
          "quality_score": 0.95,
          "reviewed": true
        }
      }
    },
    {
      "document_id": "doc_frame_002",
      "update_data": {
        "metadata": {
          "flagged": true,
          "quality_score": 0.87
        }
      }
    },
    {
      "document_id": "doc_frame_003",
      "update_data": {
        "metadata": {
          "discarded": true,
          "quality_score": 0.72
        }
      }
    }
  ]
}'
{
  "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
}

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 update documents in.

Body

application/json

Request model for batch updating multiple documents by explicit IDs or filters.

Supports TWO modes:

  1. Explicit IDs mode: Provide 'updates' array with document_id + update_data for each
  2. 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

​
updates
BatchDocumentUpdate · object[] | null

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 elements
Examples:
[
  {
    "document_id": "doc_123",
    "update_data": { "metadata": { "status": "processed" } }
  },
  {
    "document_id": "doc_456",
    "update_data": { "metadata": { "status": "archived" } }
  }
]
​
filters
object | null

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

​
update_data
object | null

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.

Response

Successful Response

Response model for batch document update operation.

Provides detailed per-document results showing success/failure for each update.

​
updated_count
integer
required

Total number of documents successfully updated

​
failed_count
integer
default:0

Total number of documents that failed to update

​
results
BatchDocumentUpdateResult · 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 update completed

Summary message of the operation