Запис документів - Conare

POST /namespaces/:namespace/documents Записуйте документи в простір імен: Conare розбиває їх на фрагменти, створює ембединги й індексує, а перший запис створює простір імен.

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" } }
    ]
  }'

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" } },
]);

Response

{
  "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	Значення для фільтрації (правила)
`user`	string	Кому належить документ (користувачі)
`seq`	integer	Ваш номер версії, від 0 до 2^53; `seq`, менший за збережений, пропускається
`if_version`	integer	Записати, лише якщо збережена `version` збігається; `0` записує лише новий документ

Повна схема: Додати документи.

Відповідь

Поле	Значення
`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.

Метадані

{ "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.

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

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

Коли створення ембедингів перевантажене, запис чекає й повертає Conare-Degraded: embed-busy: надсилайте менше записів одночасно.
Приблизно через 30 секунд він повертає 503 з Retry-After.
Невдалий запит міг записати частину документів: повторіть його з тим самим Idempotency-Key.