> ## 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 안에서 길이 제한 없음. 긴 텍스트도 문서 하나입니다 |
| `metadata` | object | [필터](https://docs.conare.ai/ko/filters.md)에 쓸 값([규칙](#메타데이터)) |
| `user` | string | 문서의 소유자([사용자](#사용자)) |
| `seq` | integer | 사용자 지정 버전 번호, 0\~2^53. 저장된 값보다 낮은 `seq`는 건너뜁니다 |
| `if_version` | integer | 저장된 `version`이 일치할 때만 씁니다. `0`이면 새 문서만 씁니다 |

전체 스키마: [문서 추가](https://docs.conare.ai/ko/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개를 더합니다 |

## 사용자

네임스페이스 하나에 여러 사용자의 문서를 담을 때 `user`를 설정한 뒤, `user` 또는 `user_prefix`로 [검색](https://docs.conare.ai/ko/query.md)하세요.

| 규칙 | |
| - | - |
| 형식 | `A-Z a-z 0-9 . _ : @ -`로 된 최대 128자, 문자나 숫자로 시작, `:`는 최대 8개 |
| 그룹 | `tenant-7:u_42`로 쓰고, 테넌트 전체는 `user_prefix: "tenant-7:"`로 검색 |
| 필터 | [필터](https://docs.conare.ai/ko/filters.md)는 `user`와 일치시킬 수 없습니다. `user`와 `user_prefix`를 사용하세요 |

## 처리량

* 임베딩이 바쁘면 쓰기가 대기하고 `Conare-Degraded: embed-busy`를 반환합니다. 동시에 보내는 쓰기를 줄이세요.
* 약 30초가 지나면 `Retry-After`와 함께 `503`을 반환합니다.
* 실패한 요청이 일부 문서를 썼을 수 있습니다. 같은 [`Idempotency-Key`](https://docs.conare.ai/ko/api#재시도)로 재시도하세요.


## Related topics

- [콘솔](https://docs.conare.ai/ko/console.md)
- [turbopuffer API](https://docs.conare.ai/ko/turbopuffer.md)
- [네임스페이스](https://docs.conare.ai/ko/namespaces.md)
- [빠른 시작](https://docs.conare.ai/ko/quickstart.md)
- [TypeScript SDK](https://docs.conare.ai/ko/sdk.md)


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