> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# 写入文档

> 在命名空间中添加或替换最多 100 个文档，Conare 会对其分块、嵌入和索引，调用返回时即可搜索。介绍选项、元数据和用户。

`POST /namespaces/:namespace/documents`

将文档写入命名空间：Conare 会对其进行分块、嵌入和索引，首次写入时会创建该命名空间。

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/documents \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "refunds", "text": "Refunds are available for 30 days.", "metadata": { "team": "support" } },
      { "id": "shipping", "text": "Orders ship within two days.", "metadata": { "team": "ops" } }
    ]
  }'
```

```ts TypeScript theme={null}
await docs.write([
  { id: "refunds", text: "Refunds are available for 30 days.", metadata: { team: "support" } },
  { id: "shipping", text: "Orders ship within two days.", metadata: { team: "ops" } },
]);
```

```json Response theme={null}
{
  "ids": ["refunds", "shipping"],
  "results": [
    { "id": "refunds", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 },
    { "id": "shipping", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 }
  ],
  "versions": [1, 1]
}
```

## 选项

| 选项 | 类型 | 作用 |
| - | - | - |
| `documents` | array，必填 | 1-100 个文档 |
| `id` | string | 最多 256 个 `A-Z a-z 0-9 . _ : -` 字符；省略时自动生成。写入已有 id 会替换该文档 |
| `text` | string，必填 | 在请求 32 MiB 的正文内长度不限；长文本仍是一个文档 |
| `metadata` | object | 用于 [过滤](https://docs.conare.ai/zh/filters.md) 的值（[规则](#元数据)） |
| `user` | string | 文档所属的用户（[用户](#用户)） |
| `seq` | integer | 你自己的版本号，0 到 2^53；`seq` 低于已存储值的写入会被跳过 |
| `if_version` | integer | 仅当已存储的 `version` 匹配时才写入；`0` 表示仅写入新文档 |

完整 schema：[添加文档](https://docs.conare.ai/zh/api-reference/documents/add-documents.md)。

## 响应

| 字段 | 含义 |
| - | - |
| `ids`, `versions` | 每个文档的 id 和版本，按请求顺序排列 |
| `results[].result` | `created`、`updated`、`unchanged`（文本、元数据和用户均相同）或 `stale`（已存储更高的 `seq`） |
| `results[].chunks` | 文档包含的段落数 |
| `results[].chunks_embedded` | 本次写入嵌入的段落数；未变更的段落不会重新嵌入 |
| `results[].stored_seq` | 结果为 `stale` 时，已存储的 `seq` |

`if_version` 不匹配时返回 `409 version_conflict`。

## 元数据

```json theme={null}
{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }
```

| 规则 | 限制 |
| - | - |
| 值 | 字符串、数字、布尔值或字符串数组 |
| 键 | 最多 32 个，每个为 1-64 个 `A-Z a-z 0-9 _ . -` 字符，以字母开头 |
| 保留键 | `id`、`text`、`vector`、`ttl_at_ms` |
| 单个字符串 | 最多 4 KiB |
| 单个数组 | 最多 256 个字符串 |
| 每个文档的不同值数量 | 总计 256：数字或不超过 222 字节的字符串计为两个；数组元素、布尔值或更长的字符串计为一个；`user` 计为一个，每个 `:` 再加一个 |

## 用户

当一个命名空间存放多个用户的文档时，请设置 `user`，然后使用 `user` 或 `user_prefix` 进行 [搜索](https://docs.conare.ai/zh/query.md)。

| 规则 | |
| - | - |
| 格式 | 最多 128 个 `A-Z a-z 0-9 . _ : @ -` 字符，以字母或数字开头，最多 8 个 `:` |
| 分组 | 写入 `tenant-7:u_42`，搜索 `user_prefix: "tenant-7:"` 即可覆盖整个租户 |
| 过滤条件 | [过滤条件](https://docs.conare.ai/zh/filters.md) 无法匹配 `user`；请使用 `user` 和 `user_prefix` |

## 吞吐量

* 嵌入繁忙时，写入会等待并返回 `Conare-Degraded: embed-busy`：请减少并发写入。
* 约 30 秒后，会返回 `503` 及 `Retry-After`。
* 失败的请求可能已写入部分文档：请使用相同的 [`Idempotency-Key`](https://docs.conare.ai/zh/api#重试) 重试。


## Related topics

- [快速入门](https://docs.conare.ai/zh/quickstart.md)
- [MCP](https://docs.conare.ai/zh/mcp-server.md)
- [简介](https://docs.conare.ai/zh/index.md)
- [获取、列出和删除文档](https://docs.conare.ai/zh/documents.md)
- [控制台](https://docs.conare.ai/zh/console.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.