Escribir documentos - Conare

POST /namespaces/:namespace/documents Escribe documentos en un namespace: Conare los divide en fragmentos, los embebe y los indexa, y la primera escritura crea el 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]
}

Opciones

Opción	Tipo	Qué hace
`documents`	array, obligatorio	De 1 a 100 documentos
`id`	string	Hasta 256 caracteres de `A-Z a-z 0-9 . _ : -`; se genera si se omite. Escribir un id existente lo reemplaza
`text`	string, obligatorio	Cualquier longitud dentro del cuerpo de 32 MiB de la petición; un texto largo sigue siendo un documento
`metadata`	object	Valores por los que filtrar (reglas)
`user`	string	A quién pertenece el documento (usuarios)
`seq`	integer	Tu número de versión, de 0 a 2^53; un `seq` inferior al almacenado se omite
`if_version`	integer	Escribe solo si la `version` almacenada coincide; `0` escribe solo un documento nuevo

Esquema completo: Añadir documentos.

Respuesta

Campo	Significado
`ids`, `versions`	El id y la versión de cada documento, en el orden de la solicitud
`results[].result`	`created`, `updated`, `unchanged` (mismo texto, metadatos y usuario) o `stale` (hay un `seq` mayor almacenado)
`results[].chunks`	Pasajes que tiene el documento
`results[].chunks_embedded`	Pasajes que embebió esta escritura; los que no cambian no se vuelven a embeber
`results[].stored_seq`	Con `stale`, el `seq` almacenado

Si if_version no coincide, se devuelve 409 version_conflict.

Metadatos

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

Regla	Límite
Valores	Strings, números, booleanos o arrays de strings
Claves	Hasta 32, cada una de 1-64 caracteres de `A-Z a-z 0-9 _ . -`, empezando por una letra
Claves reservadas	`id`, `text`, `vector`, `ttl_at_ms`
Un string	Hasta 4 KiB
Un array	Hasta 256 strings
Valores distintos por documento	256 en total: un número o un string de hasta 222 bytes cuenta dos; un elemento de array, un booleano o un string más largo, uno; un `user`, uno, más uno por cada `:`

Usuarios

Define user cuando un namespace contiene documentos de muchos usuarios, y luego busca con user o user_prefix.

Regla
Formato	Hasta 128 caracteres de `A-Z a-z 0-9 . _ : @ -`, empezando por una letra o un dígito, con 8 `:` como máximo
Grupos	Escribe `tenant-7:u_42` y busca `user_prefix: "tenant-7:"` para todo el tenant
Filtros	Un filtro no puede coincidir con `user`; usa `user` y `user_prefix`

Rendimiento

Cuando el embedding está ocupado, una escritura espera y devuelve Conare-Degraded: embed-busy: envía menos escrituras a la vez.
Tras unos 30 segundos devuelve 503 con Retry-After.
Una solicitud fallida puede haber escrito algunos documentos: reinténtala con la misma Idempotency-Key.