---
title: "Create or Update Chunk Relations in Batches"
method: PUT
path: "/v3/collections/{collection_name}/relations/batch"
tags: ["file-search"]
---

# Create or Update Chunk Relations in Batches

`PUT /v3/collections/{collection_name}/relations/batch`

Create or update up to 100 chunk relations in one request. A relation is identified by its source chunk, target chunk, and `relation_type`. When no relation with that identity exists, one is created and the item returns 201. When exactly one exists, it keeps its `relation_id` and its entire `metadata` object is replaced: keys omitted from the item are removed, and `{}` clears the metadata. Relations not named in the request are left unchanged. This differs from [Create Chunk Relation](/reference/v3/documents/chunk/relations/create), which always creates and can therefore produce duplicate relations; when more than one existing relation matches an item's identity, the batch changes nothing and fails that item with 409 `relation_identity_ambiguous`. 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

- BatchRelationUpsertRequestV3 — Always an object with one key, `items`, even for a single item. A bare item object is rejected with 400.
  - `items` BatchRelationUpsertItemV3[], 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.
    - `source_chunk_id` string, required — Chunk ID where the relation starts.
    - `target_chunk_id` string, required — Chunk ID where the relation points. Must differ from `source_chunk_id`.
    - `relation_type` string, required — Application-defined relation label. Part of the relation's identity together with the source and target chunk.
    - `metadata` object, required — Required. On create, the relation's metadata. On update, replaces the existing relation's entire metadata object: omitted keys are removed, and `{}` clears it.
    - `target_document_id` string, nullable — Optional. When supplied, the document must contain the target chunk. It does not change the relation's identity.

## Response `200`

Create or Update Chunk Relations in Batches response.

- BatchRelationUpsertResponseV3
  - `results` BatchRelationUpsertResultV3[], 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`. `http_status` is 201 for a created relation and 200 for an updated one.
        - `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` ChunkRelationResponseV3, required
          - `relation` ChunkRelationFromV3, required
            - `relation_id` string, required
            - `source_chunk_id` string, required
            - `target_chunk_id` string, required
            - `target_document_id` string, nullable
            - `target_status` 'found' | 'missing' | 'unknown'
            - `relation_type` string, required
            - `metadata` ChunkRelationFromV3Metadata
            - `created_at` string, nullable
            - `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/relations/batch/put.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)