Bulk Update Documents

Bulk update documents matching filter conditions.

Partially updates all documents in the collection that match the provided filters. If no filters are provided, updates all documents in the collection.

This endpoint applies the SAME update_data to ALL documents matching the filters. For per-document updates with different values, use POST /batch endpoint instead.

PATCH /v1/collections/{collection_identifier}/documents/bulk

Bulk Update Documents

cURL

curl --request PATCH \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Update all pending documents to processed",
  "filters": {
    "AND": [
      {
        "field": "metadata.status",
        "operator": "eq",
        "value": "pending"
      }
    ]
  },
  "update_data": {
    "metadata.status": "processed"
  }
}
'

200

{
  "task_id": "<string>",
  "status": "<string>",
  "updated_count": 123,
  "message": "Bulk update enqueued"
}

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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

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

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for bulk updating documents by filters.

Updates ALL documents matching the provided filters with the SAME update_data. For updating specific documents by ID or different values per document, use BatchUpdateDocumentsRequest.

Use Cases: - Update all pending documents to processed - Update all documents from a specific date range - Apply uniform changes across filtered document sets

Requirements: - update_data: REQUIRED - fields to update on all matching documents - filters: OPTIONAL - if omitted, updates ALL documents in collection

update_data · Update Data · object · required

REQUIRED. Dictionary of field-value pairs to update on ALL matching documents. Can update any document field except vectors (metadata, source_blobs, etc.). All matched documents receive the SAME updates. 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. Object values are stored as given, but read back with their keys in alphabetical order. Example: {'metadata.status': 'processed', 'metadata.reviewed': true}

Examples:

{
  "metadata.reviewed": true,
  "metadata.status": "processed"
}

{ "metadata.processing_complete": true }

filters · LogicalOperator · object | null

OPTIONAL. Filter conditions to match documents for update. If not provided, updates ALL documents in the collection. Uses the logical AND/OR/NOT shape — a list of {field, operator, value} conditions (operators: eq, ne, in, nin, gt, gte, lt, lte, contains, exists, …). The MVS-native {'must': [{'key': ...}]} shape is NOT accepted here. Example: {'AND': [{'field': 'metadata.status', 'operator': 'eq', 'value': 'pending'}]}

Show child attributes

Example:

{
  "AND": [
    {
      "field": "metadata.status",
      "operator": "eq",
      "value": "pending"
    }
  ]
}

Response

200

application/json

Successful Response

Response model for bulk document update operation.

bulk update is ASYNC. A filtered update scrolls matches on the shard and can run far longer than a request should hold a connection (an unindexed filtered scroll scans the whole shard, so 172 matching docs on a shared 6.47M-vector shard exceeded 120s and the client saw a silent no-op). The endpoint now enqueues a task and returns immediately: poll GET /v1/tasks/{task_id} for the terminal status and updated_count.

task_id · string | null

Id of the background task running the bulk update. Poll GET /v1/tasks/{task_id} for status and the final updated_count.

status · string | null

Task status at enqueue time (PENDING). The terminal status (COMPLETED / FAILED) and updated_count land on the task record.

updated_count · integer | null

Number of documents updated. Null on the async enqueue response; populated on the task record when the task completes.

message · string · default: Bulk update enqueued