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

# Scrivere documenti

> Aggiungi o sostituisci fino a 100 documenti in un namespace; sono ricercabili quando la chiamata risponde.

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

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

## 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](https://docs.conare.ai/it/filters.md) ([regole](#metadati)) |
| `user` | string | A chi appartiene il documento ([utenti](#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](https://docs.conare.ai/it/api-reference/documents/add-documents.md).

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

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


## Related topics

- [Introduzione](https://docs.conare.ai/it/index.md)
- [Console](https://docs.conare.ai/it/console.md)
- [Ottenere, elencare ed eliminare documenti](https://docs.conare.ai/it/documents.md)
- [Delete documents by id or filter](https://docs.conare.ai/it/api-reference/documents/delete-documents-by-id-or-filter.md)
- [Filtri](https://docs.conare.ai/it/filters.md)


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