> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Écrire des documents

> Ajoutez ou remplacez jusqu'à 100 documents dans un namespace ; ils sont consultables dès le retour de l'appel.

`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.

```bash curl theme={null}
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" } }
    ]
  }'
```

```ts TypeScript theme={null}
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" } },
]);
```

```json Response theme={null}
{
  "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](https://docs.conare.ai/fr/filters.md) ([règles](#métadonnées)) |
| `user` | string | À qui appartient le document ([utilisateurs](#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](https://docs.conare.ai/fr/api-reference/documents/add-documents.md).

## 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

```json theme={null}
{ "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](https://docs.conare.ai/fr/query.md) 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](https://docs.conare.ai/fr/filters.md) 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`](https://docs.conare.ai/fr/api#nouvelles-tentatives).


## Related topics

- [Introduction](https://docs.conare.ai/fr/index.md)
- [Obtenir, lister et supprimer des documents](https://docs.conare.ai/fr/documents.md)
- [Console](https://docs.conare.ai/fr/console.md)
- [Démarrage rapide](https://docs.conare.ai/fr/quickstart.md)
- [Recherche](https://docs.conare.ai/fr/query.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.