Écrire des documents - Conare

POST /namespaces/:namespace/documents Écrivez des documents dans un namespace : Conare les découpe, les vectorise et les indexe, et la première écriture crée le 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]
}

Options

Option	Type	Rôle
`documents`	array, obligatoire	1 à 100 documents
`id`	string	Jusqu’à 256 caractères parmi `A-Z a-z 0-9 . _ : -` ; généré si omis. Écrire un id existant le remplace
`text`	string, obligatoire	Toute longueur dans le corps de 32 Mio de la requête ; un texte long reste un seul document
`metadata`	object	Valeurs sur lesquelles filtrer (règles)
`user`	string	À qui appartient le document (utilisateurs)
`seq`	integer	Votre numéro de version, de 0 à 2^53 ; un `seq` inférieur à celui stocké est ignoré
`if_version`	integer	N’écrit que si la `version` stockée correspond ; `0` n’écrit qu’un nouveau document

Schéma complet : Ajouter des documents.

Réponse

Champ	Signification
`ids`, `versions`	L’id et la version de chaque document, dans l’ordre de la requête
`results[].result`	`created`, `updated`, `unchanged` (même texte, mêmes métadonnées et même utilisateur) ou `stale` (un `seq` supérieur est stocké)
`results[].chunks`	Passages que contient le document
`results[].chunks_embedded`	Passages vectorisés par cette écriture ; les passages inchangés ne sont pas revectorisés
`results[].stored_seq`	Avec `stale`, le `seq` stocké

Un if_version qui ne correspond pas renvoie 409 version_conflict.

Métadonnées

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

Règle	Limite
Valeurs	Chaînes, nombres, booléens ou tableaux de chaînes
Clés	Jusqu’à 32, chacune de 1 à 64 caractères parmi `A-Z a-z 0-9 _ . -`, commençant par une lettre
Clés réservées	`id`, `text`, `vector`, `ttl_at_ms`
Une chaîne	Jusqu’à 4 KiB
Un tableau	Jusqu’à 256 chaînes
Valeurs distinctes par document	256 au total : un nombre ou une chaîne de 222 octets au plus compte pour deux ; un élément de tableau, un booléen ou une chaîne plus longue pour un ; un `user` pour un, plus un par `:`

Utilisateurs

Définissez user quand un namespace contient les documents de nombreux utilisateurs, puis recherchez avec user ou user_prefix.

Règle
Format	Jusqu’à 128 caractères parmi `A-Z a-z 0-9 . _ : @ -`, commençant par une lettre ou un chiffre, avec 8 `:` au plus
Groupes	Écrivez `tenant-7:u_42`, recherchez `user_prefix: "tenant-7:"` pour tout le tenant
Filtres	Un filtre ne peut pas cibler `user` ; utilisez `user` et `user_prefix`

Débit

Quand la vectorisation est saturée, une écriture attend et renvoie Conare-Degraded: embed-busy : envoyez moins d’écritures simultanées.
Après environ 30 secondes, elle renvoie 503 avec Retry-After.
Une requête échouée peut avoir écrit certains documents : réessayez-la avec la même Idempotency-Key.