> ## 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 件のドキュメントを追加または置換します。呼び出しが返った時点で検索可能です。

`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 | `A-Z a-z 0-9 . _ : -` からなる最大 256 文字。省略すると生成されます。既存の ID に書き込むと置換されます |
| `text` | string、必須 | リクエストの 32 MiB の本文に収まれば長さは自由です。長いテキストも 1 つのドキュメントです |
| `metadata` | object | [フィルター](https://docs.conare.ai/ja/filters.md)に使う値([ルール](#メタデータ)) |
| `user` | string | ドキュメントの所有者([ユーザー](#ユーザー)) |
| `seq` | integer | 独自のバージョン番号(0〜2^53)。保存済みより小さい `seq` はスキップされます |
| `if_version` | integer | 保存済みの `version` と一致する場合のみ書き込みます。`0` は新規ドキュメントのみ書き込みます |

完全なスキーマ: [ドキュメントを追加する](https://docs.conare.ai/ja/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 個。各キーは `A-Z a-z 0-9 _ . -` からなる 1〜64 文字で、英字で始まります |
| 予約済みキー | `id`、`text`、`vector`、`ttl_at_ms` |
| 文字列 | 最大 4 KiB |
| 配列 | 最大 256 個の文字列 |
| ドキュメントあたりの異なる値 | 合計 256。数値または 222 バイト以下の文字列は 2 として数え、配列の要素、ブール値、それより長い文字列は 1 として数えます。`user` は 1 に加えて `:` ごとに 1 です |

## ユーザー

1 つのネームスペースに多数のユーザーのドキュメントを保持する場合は `user` を設定し、`user` または `user_prefix` で[検索](https://docs.conare.ai/ja/query.md)します。

| ルール | |
| - | - |
| 形式 | `A-Z a-z 0-9 . _ : @ -` からなる最大 128 文字。英字または数字で始まり、`:` は最大 8 個 |
| グループ | `tenant-7:u_42` と書き込み、`user_prefix: "tenant-7:"` で検索するとテナント全体が対象になります |
| フィルター | [フィルター](https://docs.conare.ai/ja/filters.md)は `user` に一致できません。`user` と `user_prefix` を使ってください |

## スループット

* 埋め込みが混雑しているとき、書き込みは待機して `Conare-Degraded: embed-busy` を返します。同時に送る書き込みを減らしてください。
* 約 30 秒後には `Retry-After` 付きで `503` を返します。
* 失敗したリクエストでも一部のドキュメントが書き込まれている場合があります。同じ [`Idempotency-Key`](https://docs.conare.ai/ja/api#再試行) で再試行してください。


## Related topics

- [クイックスタート](https://docs.conare.ai/ja/quickstart.md)
- [ドキュメントの取得、一覧表示、削除](https://docs.conare.ai/ja/documents.md)
- [MCP](https://docs.conare.ai/ja/mcp-server.md)
- [はじめに](https://docs.conare.ai/ja/index.md)
- [コンソール](https://docs.conare.ai/ja/console.md)


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