Overwrite Document Metadata in Batches

import json
import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
response = requests.put(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/documents/metadata/batch",
    headers=headers,
    json={
        "items": [
            {
                "item_id": "update-1",
                "document_id": "doc-a",
                "metadata": {
                    "review_status": "reviewed"
                }
            },
            {
                "item_id": "update-2",
                "document_id": "doc-b",
                "metadata": {
                    "review_status": "pending"
                }
            }
        ]
    },
    timeout=60.0
)
for result in response.json()["results"]:
    print(result["item_id"], result["status"], result["http_status"])

{
  "results": [
    {
      "status": "succeeded",
      "data": {
        "document_id": "doc-a",
        "custom_metadata": {
          "review_status": "reviewed"
        },
        "filterable": true
      },
      "http_status": 200,
      "item_id": "update-1"
    },
    {
      "status": "failed",
      "error": {
        "code": "target_not_found",
        "message": "Target not found."
      },
      "http_status": 404,
      "item_id": "update-2"
    }
  ]
}

Overwrite the custom_metadata object on up to 100 documents in one request. Each item behaves like Overwrite Document Metadata. Returns 200 with one result per item, in order. Overwrite is destructive: omitted keys are removed and {} clears the target. Consider copying the collection first. Envelope, partial success, and unknown outcomes are covered in the Batch Metadata & Relations guide.

Overwrite the `custom_metadata` object on up to 100 documents in one request. Each item behaves like [Overwrite Document Metadata](/reference/v3/document/metadata/replace). Returns 200 with one result per item, in order. Overwrite is destructive: omitted keys are removed and `{}` clears the target. Consider [copying the collection](/reference/collections/copy) first. Envelope, partial success, and `unknown` outcomes are covered in the [Batch Metadata & Relations](/guides/batch-writes) guide.

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

itemslist of objectsRequired

1 to 100 items. The request body may not exceed 1 MiB of UTF-8 JSON.

Response

Overwrite Document Metadata in Batches response.

resultslist of objects

One result per request item, in request order. Never empty for an accepted batch.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

413

Content Too Large Error