> ## 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 | До 256 символів із `A-Z a-z 0-9 . _ : -`; генерується, якщо не вказано. Запис наявного id замінює документ |
| `text` | string, обов’язковий | Будь-якої довжини в межах 32 MiB тіла запиту; довгий текст лишається одним документом |
| `metadata` | object | Значення для [фільтрації](https://docs.conare.ai/uk/filters.md) ([правила](#метадані)) |
| `user` | string | Кому належить документ ([користувачі](#користувачі)) |
| `seq` | integer | Ваш номер версії, від 0 до 2^53; `seq`, менший за збережений, пропускається |
| `if_version` | integer | Записати, лише якщо збережена `version` збігається; `0` записує лише новий документ |

Повна схема: [Додати документи](https://docs.conare.ai/uk/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`, коли один простір імен містить документи багатьох користувачів, а потім [шукайте](https://docs.conare.ai/uk/query.md) з `user` або `user_prefix`.

| Правило | |
| - | - |
| Формат | До 128 символів із `A-Z a-z 0-9 . _ : @ -`, починається з літери або цифри, не більше 8 `:` |
| Групи | Записуйте `tenant-7:u_42`, шукайте з `user_prefix: "tenant-7:"` для всього орендаря |
| Фільтри | [Фільтр](https://docs.conare.ai/uk/filters.md) не може відповідати `user`; використовуйте `user` і `user_prefix` |

## Пропускна здатність

* Коли створення ембедингів перевантажене, запис чекає й повертає `Conare-Degraded: embed-busy`: надсилайте менше записів одночасно.
* Приблизно через 30 секунд він повертає `503` з `Retry-After`.
* Невдалий запит міг записати частину документів: повторіть його з тим самим [`Idempotency-Key`](https://docs.conare.ai/uk/api#повтори).


## Related topics

- [Вступ](https://docs.conare.ai/uk/index.md)
- [Простори імен](https://docs.conare.ai/uk/namespaces.md)
- [Огляд API](https://docs.conare.ai/uk/api.md)
- [Отримання, перелік і видалення документів](https://docs.conare.ai/uk/documents.md)
- [Google Cloud Storage](https://docs.conare.ai/uk/gcs.md)


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