Create or Update Chunk Relations 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}/relations/batch",
    headers=headers,
    json={
        "items": [
            {
                "item_id": "link-1",
                "source_chunk_id": "file-a:3",
                "target_chunk_id": "file-a:8",
                "relation_type": "supported_by",
                "metadata": {
                    "review_status": "reviewed"
                }
            },
            {
                "item_id": "link-2",
                "source_chunk_id": "file-b:2",
                "target_chunk_id": "file-b:9",
                "relation_type": "supported_by",
                "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": {
        "relation": {
          "relation_id": "rel-1",
          "source_chunk_id": "file-a:3",
          "target_chunk_id": "file-a:8",
          "relation_type": "supported_by",
          "metadata": {
            "review_status": "reviewed"
          }
        }
      },
      "http_status": 201,
      "item_id": "link-1"
    },
    {
      "status": "failed",
      "error": {
        "code": "target_not_found",
        "message": "Source or target chunk not found."
      },
      "http_status": 404,
      "item_id": "link-2"
    }
  ]
}

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, 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 guide.

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_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

Create or Update Chunk Relations 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