# Replace documents

URL: https://docs.hanzo.ai/docs/openapi/index/put-index-indexes-by-uid-documents

> The dialect's update spelling of the write above, and the same act: an upsert keyed by the index's primary key.

`PUT /v1/index/indexes/{uid}/documents`

> [Index →](https://docs.hanzo.ai/docs/openapi/index) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                         |
| ------------- | ------------------------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/index/indexes/{uid}/documents` |
| **Method**    | `PUT`                                                   |
| **Operation** | `put_index_indexes_by_uid_documents`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`                  |

The dialect's update spelling of the write above, and the same act: an upsert keyed by the index's primary key. The JS client's addDocuments and updateDocuments both reduce to this for whole documents, so both spellings are served and both behave identically.

The tenant is the org minted from the VALIDATED bearer's owner claim, never a client-supplied header. Without a validated principal the answer is 403 carrying the dialect's `invalid_api_key` body.

The 202 and its `enqueued` task are DIALECT COMPATIBILITY, not a promise of later work: the write is already applied when this answers.

## Request

2 fields, body `application/json`.

| Field    | In   | Type             | Required | Description |
| -------- | ---- | ---------------- | -------- | ----------- |
| `uid`    | path | string           | yes      |             |
| `(body)` | body | any\[] \| object | yes      |             |

## Response

| Status | Body          | Meaning |
| ------ | ------------- | ------- |
| `2XX`  | indexEnqueued | Success |

`2XX` body — 5 fields.

| Field        | In   | Type    | Always | Description |
| ------------ | ---- | ------- | ------ | ----------- |
| `enqueuedAt` | body | string  | —      |             |
| `indexUid`   | body | string  | —      |             |
| `status`     | body | string  | —      |             |
| `taskUid`    | body | integer | —      |             |
| `type`       | body | string  | —      |             |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo index indexes documents replace <uid>
```

**SDK**

**.ts**

```ts
import { Configuration, IndexApi } from 'hanzoai';

const api = new IndexApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putIndexIndexesByUidDocuments({ uid: 'uid' });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import IndexApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = IndexApi(client).put_index_indexes_by_uid_documents(uid='uid')
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.IndexAPI.PutIndexIndexesByUidDocuments(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, index_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = index_api::put_index_indexes_by_uid_documents(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.IndexApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new IndexApi(client).putIndexIndexesByUidDocuments();
```

**HTTP**

```bash
curl -X PUT https://api.hanzo.ai/v1/index/indexes/<uid>/documents \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

MCP reaches **index** through the `index` tool, which names its 14 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_index_health"
         }
       }
     }'
```

---

[Index API](https://docs.hanzo.ai/docs/openapi/index) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)