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

# Overwrite Document Metadata

PUT https://api.captain.dev/v3/collections/{collection_name}/documents/{document_id}/metadata
Content-Type: application/json

Overwrite a document's `custom_metadata` with the object in this request; keys omitted here are removed, including from the search filter index. Bulk indexing stamps one metadata object per request, so per-file values (such as an ID from your own system) are set here after indexing.

Reference: https://docs.captain.dev/reference/v3/document/metadata/replace

## Request

### Path parameters

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

### Body (application/json)

This endpoint expects an UpdateChunkMetadataRequestV3.

- `custom_metadata` (map from string to any, optional) — The custom metadata object. Keys that Captain uses for its own chunk attributes are reserved and rejected with 400.
- `metadata` (map from string to any, optional, deprecated) — Deprecated alias for `custom_metadata`.

## Response

### 200

Overwrite Document Metadata response.

- `document_id` (string, required)
- `custom_metadata` (map from string to any, optional)
- `filterable` (boolean, optional, default: false)
- `updated_at` (string, optional, nullable)

## Examples

**Request**

```json
{
  "custom_metadata": {
    "external_id": "doc_18842",
    "client": "acme-lending"
  }
}
```

**Response**

```json
{
  "document_id": "b3f9a1c2d4e5f60718293a4b5c6d7e8f",
  "custom_metadata": {
    "external_id": "doc_18842",
    "client": "acme-lending"
  },
  "filterable": true,
  "updated_at": null
}
```

**SDK Code**

```python
import json
import requests
import uuid

BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"
DOCUMENT_ID = "b3f9a1c2d4e5f60718293a4b5c6d7e8f"

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

response = requests.put(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/documents/{DOCUMENT_ID}/metadata",
    headers=headers,
    json={
    "custom_metadata": {
        "external_id": "doc_18842",
        "client": "acme-lending"
    }
},
    timeout=30.0
)

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

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

const API_KEY = "your_api_key";

const collection_name = "my_documents";

const document_id = "b3f9a1c2d4e5f60718293a4b5c6d7e8f";

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

const response = await fetch(`${BASE_URL}/v3/collections/${collection_name}/documents/${document_id}/metadata`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
  "custom_metadata": {
    "external_id": "doc_18842",
    "client": "acme-lending"
  }
}),
});

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