Update 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.patch(
    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",
          "owner": "team-a"
        },
        "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"
    }
  ]
}

Merge custom_metadata into up to 100 documents in one request. Each item behaves like Update Document Metadata: supplied keys are merged, omitted keys kept, null deletes a key. Returns 200 with one result per item, in order. Envelope, partial success, and unknown outcomes are covered in the Batch Metadata & Relations guide.

Merge `custom_metadata` into up to 100 documents in one request. Each item behaves like [Update Document Metadata](/reference/v3/document/metadata/update): supplied keys are merged, omitted keys kept, `null` deletes a key. Returns 200 with one result per item, in order. 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

Update 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