Scrivere documenti - Conare

POST /namespaces/:namespace/documents Scrivi documenti in un namespace: Conare li suddivide in chunk, genera gli embedding e li indicizza, e la prima scrittura crea il 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]
}

Opzioni

Opzione	Tipo	Cosa fa
`documents`	array, obbligatorio	Da 1 a 100 documenti
`id`	string	Fino a 256 caratteri tra `A-Z a-z 0-9 . _ : -`; generato se omesso. Scrivere un id esistente lo sostituisce
`text`	string, obbligatorio	Qualsiasi lunghezza entro il corpo di 32 MiB della richiesta; un testo lungo resta un unico documento
`metadata`	object	Valori su cui filtrare (regole)
`user`	string	A chi appartiene il documento (utenti)
`seq`	integer	Il tuo numero di versione, da 0 a 2^53; un `seq` inferiore a quello salvato viene ignorato
`if_version`	integer	Scrive solo se la `version` salvata corrisponde; `0` scrive solo un nuovo documento

Schema completo: Aggiungere documenti.

Risposta

Campo	Significato
`ids`, `versions`	L’id e la versione di ogni documento, nell’ordine della richiesta
`results[].result`	`created`, `updated`, `unchanged` (stesso testo, metadati e utente) o `stale` (è salvato un `seq` più alto)
`results[].chunks`	I passaggi del documento
`results[].chunks_embedded`	I passaggi di cui questa scrittura ha generato gli embedding; quelli invariati non vengono rielaborati
`results[].stored_seq`	Con `stale`, il `seq` salvato

Un if_version non corrispondente restituisce 409 version_conflict.

Metadati

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

Regola	Limite
Valori	Stringhe, numeri, booleani o array di stringhe
Chiavi	Fino a 32, ciascuna di 1-64 caratteri tra `A-Z a-z 0-9 _ . -`, che inizia con una lettera
Chiavi riservate	`id`, `text`, `vector`, `ttl_at_ms`
Una stringa	Fino a 4 KiB
Un array	Fino a 256 stringhe
Valori distinti per documento	256 in tutto: un numero o una stringa fino a 222 byte conta due; un elemento di array, un booleano o una stringa più lunga uno; un `user` uno, più uno per ogni `:`

Utenti

Imposta user quando un namespace contiene i documenti di molti utenti, poi cerca con user o user_prefix.

Regola
Formato	Fino a 128 caratteri tra `A-Z a-z 0-9 . _ : @ -`, che inizia con una lettera o una cifra, al massimo 8 `:`
Gruppi	Scrivi `tenant-7:u_42`, cerca `user_prefix: "tenant-7:"` per l’intero tenant
Filtri	Un filtro non può corrispondere a `user`; usa `user` e `user_prefix`

Throughput

Quando la generazione degli embedding è occupata, una scrittura attende e restituisce Conare-Degraded: embed-busy: invia meno scritture contemporaneamente.
Dopo circa 30 secondi restituisce 503 con Retry-After.
Una richiesta non riuscita potrebbe aver scritto alcuni documenti: ritentala con lo stesso Idempotency-Key.