> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# Create Chunk Relation

POST https://api.filesearch.dev/v3/collections/{collection_name}/chunks/{chunk_id}/relations
Content-Type: application/json

Create a typed relation from one chunk to another chunk.

Reference: https://docs.filesearch.dev/reference/v3/documents/chunk/relations/create

## Request

### Path parameters

- `collection_name` (string, required)
- `chunk_id` (string, required)

### Body (application/json)

This endpoint expects a CreateChunkRelationRequestV3.

- `target_chunk_id` (string, required)
- `relation_type` (string, required)
- `target_document_id` (string, optional, nullable)
- `metadata` (CreateChunkRelationRequestV3Metadata, optional)

## Response

### 201

Successful Response

- `relation` (ChunkRelationFromV3, required)

## Errors

### 400 Bad Request Error

Source and target chunk IDs must differ.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 401 Unauthorized Error

Missing or invalid authentication.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 403 Forbidden Error

API key cannot write to this collection.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 404 Not Found Error

Collection not found.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

## Types

### CreateChunkRelationRequestV3Metadata

### ChunkRelationFromV3

- `relation_id` (string, required)
- `source_chunk_id` (string, required)
- `target_chunk_id` (string, required)
- `relation_type` (string, required)
- `target_document_id` (string, optional, nullable)
- `target_status` (enum, optional, default: unknown)
  - Allowed values: `found`, `missing`, `unknown`
- `metadata` (ChunkRelationFromV3Metadata, optional)
- `created_at` (string, optional, nullable)
- `updated_at` (string, optional, nullable)

### ChunkRelationFromV3Metadata

## Examples

**Request**

```json
{
  "target_chunk_id": "chunk_ipcc_summary_014",
  "relation_type": "cites",
  "target_document_id": "doc_ipcc_summary_2023",
  "metadata": {
    "citation": "IPCC AR6 WGII Chapter 5"
  }
}
```

**SDK Code**

```python
import json
import requests
import uuid

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"
CHUNK_ID = "doc_abc123:0"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}

response = requests.post(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/chunks/{CHUNK_ID}/relations",
    headers=headers,
    json={
    "target_chunk_id": "chunk_ipcc_summary_014",
    "target_document_id": "doc_ipcc_summary_2023",
    "relation_type": "cites",
    "metadata": {
        "citation": "IPCC AR6 WGII Chapter 5"
    }
},
    timeout=30.0
)

print(json.dumps(response.json(), indent=2))
```

```typescript
const BASE_URL = "https://api.filesearch.dev";

const API_KEY = "your_api_key";

const collection_name = "my_documents";

const chunk_id = "doc_abc123:0";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": crypto.randomUUID(),
};

const response = await fetch(`${BASE_URL}/v3/collections/${collection_name}/chunks/${chunk_id}/relations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "target_chunk_id": "chunk_ipcc_summary_014",
    "target_document_id": "doc_ipcc_summary_2023",
    "relation_type": "cites",
    "metadata": {
      "citation": "IPCC AR6 WGII Chapter 5"
    }
  }),
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));
```