Gravar documentos - Conare

POST /namespaces/:namespace/documents Grave documentos em um namespace: a Conare os divide em chunks, gera embeddings e os indexa, e a primeira gravação cria o namespace.

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

Opções

Opção	Tipo	O que faz
`documents`	array, obrigatório	De 1 a 100 documentos
`id`	string	Até 256 caracteres de `A-Z a-z 0-9 . _ : -`; gerado se omitido. Gravar um id existente o substitui
`text`	string, obrigatório	Qualquer tamanho dentro do corpo de 32 MiB da requisição; um texto longo continua sendo um documento
`metadata`	object	Valores para filtrar (regras)
`user`	string	A quem o documento pertence (usuários)
`seq`	integer	Seu número de versão, de 0 a 2^53; um `seq` menor que o armazenado é ignorado
`if_version`	integer	Grava só se a `version` armazenada coincidir; `0` grava só um documento novo

Schema completo: Adicionar documentos.

Resposta

Campo	Significado
`ids`, `versions`	O id e a versão de cada documento, na ordem da requisição
`results[].result`	`created`, `updated`, `unchanged` (mesmo texto, metadados e usuário) ou `stale` (um `seq` maior está armazenado)
`results[].chunks`	Trechos que o documento tem
`results[].chunks_embedded`	Trechos com embedding gerado nesta gravação; os inalterados não são processados de novo
`results[].stored_seq`	Com `stale`, o `seq` armazenado

Uma divergência de if_version retorna 409 version_conflict.

Metadados

{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }

Regra	Limite
Valores	Strings, números, booleanos ou arrays de strings
Chaves	Até 32, cada uma com 1-64 caracteres de `A-Z a-z 0-9 _ . -`, começando com uma letra
Chaves reservadas	`id`, `text`, `vector`, `ttl_at_ms`
Uma string	Até 4 KiB
Um array	Até 256 strings
Valores distintos por documento	256 no total: um número ou uma string de até 222 bytes conta dois; um item de array, um booleano ou uma string mais longa, um; um `user`, um, mais um por `:`

Usuários

Defina user quando um namespace guarda documentos de muitos usuários e depois busque com user ou user_prefix.

Regra
Formato	Até 128 caracteres de `A-Z a-z 0-9 . _ : @ -`, começando com uma letra ou dígito, no máximo 8 `:`
Grupos	Grave `tenant-7:u_42` e busque `user_prefix: "tenant-7:"` para o tenant inteiro
Filtros	Um filtro não pode corresponder a `user`; use `user` e `user_prefix`

Throughput

Quando a geração de embeddings está ocupada, uma gravação espera e retorna Conare-Degraded: embed-busy: envie menos gravações ao mesmo tempo.
Após cerca de 30 segundos, ela retorna 503 com Retry-After.
Uma requisição com falha pode ter gravado alguns documentos: repita-a com o mesmo Idempotency-Key.