---
title: "Update Document Metadata in Batches"
method: PATCH
path: "/v3/collections/{collection_name}/documents/metadata/batch"
tags: ["file-search"]
---

# Update Document Metadata in Batches

`PATCH /v3/collections/{collection_name}/documents/metadata/batch`

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_name` string, required

## Request body

- BatchDocumentMetadataRequestV3 — Always an object with one key, `items`, even for a single item. A bare item object is rejected with 400.
  - `items` BatchDocumentMetadataItemV3[], required — 1 to 100 items. The request body may not exceed 1 MiB of UTF-8 JSON.
    - `item_id` string, required — Non-empty string, unique within the request. Echoed on the matching result. Not an idempotency key.
    - `document_id` string, required — A document ID returned by an indexing job or the document list. Filenames and guessed IDs are not accepted.
    - `metadata` object, required — Custom metadata for this item. Reserved keys are rejected the same way the single-item endpoint rejects them.

## Response `200`

Update Document Metadata in Batches response.

- BatchDocumentMetadataResponseV3
  - `results` BatchDocumentMetadataResultV3[], required — One result per request item, in request order. Never empty for an accepted batch.
    - union — One entry per request item, in request order. Exactly one of `data` (status `succeeded`) or `error` (status `failed` or `unknown`) is present; a result never carries both or neither.
      - object — A succeeded item: carries `data` and never `error`.
        - `status` 'succeeded', required
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `data` DocumentMetadataResponseV3, required — Response for the document-metadata write endpoints (CAP-659).
          - `custom_metadata` object
          - `document_id` string, required
          - `filterable` boolean
          - `updated_at` string, nullable
      - object — A failed or unknown item: carries `error` and never `data`. `failed` is a definite failure; `unknown` (http_status 500, code `outcome_unknown`) means the write's outcome could not be confirmed, so read the target back before replaying.
        - `status` 'failed', required — Discriminator value: failed
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `error` BatchItemErrorV3, required
          - `code` string, required — Stable error code. Item-level codes are the ones the matching single-item endpoint uses for the same failure, plus `outcome_unknown` and `relation_identity_ambiguous`.
          - `message` string, required
      - object — A failed or unknown item: carries `error` and never `data`. `failed` is a definite failure; `unknown` (http_status 500, code `outcome_unknown`) means the write's outcome could not be confirmed, so read the target back before replaying.
        - `status` 'unknown', required — Discriminator value: unknown
        - `item_id` string, required — Echoed from the request item.
        - `http_status` integer, required — The status the matching single-item endpoint would have returned for this item.
        - `error` BatchItemErrorV3, required
          - `code` string, required — Stable error code. Item-level codes are the ones the matching single-item endpoint uses for the same failure, plus `outcome_unknown` and `relation_identity_ambiguous`.
          - `message` string, required

## Other responses

- `400` — Rejected before any write: malformed envelope, item count outside 1 to 100, duplicate `item_id` or targets, or a structural field error.
- `401` — Missing or invalid authentication.
- `403` — API key cannot write to this collection.
- `404` — Collection not found. A missing item target is reported inside `results[]`.
- `413` — Request body larger than 1 MiB.

## Changes

- **2026-09-24** `61a9364ad042` — 3 warning, 12 info
  - removed the optional property `detail` from the response with the `401` status
  - removed the optional property `detail` from the response with the `403` status
  - removed the optional property `detail` from the response with the `404` status
  - added the optional property `status_code` to the response with the `401` status
  - …11 more
- **2026-09-17** `6ed36830de71` — 1 breaking, 1 info
  - added `subschema #2, subschema #3` to the `results/items/` response property `oneOf` list for the response status `200`
  - removed `subschema #2, subschema #3` from the `results/items/` response property `oneOf` list for the response status `200`
- **2026-09-15** `cce532822415` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/runcaptain/apis/api-reference/changes/v3/collections/:collection_name/documents/metadata/batch/patch.md)

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/runcaptain/apis/api-reference/revisions/ac61e472bb7d?raw)