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

# Dokumente schreiben

> Bis zu 100 Dokumente in einem Namespace hinzufügen oder ersetzen; sie sind durchsuchbar, sobald der Aufruf zurückkehrt.

`POST /namespaces/:namespace/documents`

Schreiben Sie Dokumente in einen Namespace: Conare zerlegt sie in Chunks, bettet sie ein und indexiert sie, und der erste Schreibvorgang legt den Namespace an.

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

## Optionen

| Option | Typ | Funktion |
| - | - | - |
| `documents` | array, erforderlich | 1-100 Dokumente |
| `id` | string | Bis zu 256 Zeichen aus `A-Z a-z 0-9 . _ : -`; wird ohne Angabe generiert. Das Schreiben einer bestehenden Id ersetzt sie |
| `text` | string, erforderlich | Beliebig lang innerhalb des 32-MiB-Bodys der Anfrage; ein langer Text bleibt ein Dokument |
| `metadata` | object | Werte zum [Filtern](https://docs.conare.ai/de/filters.md) ([Regeln](#metadaten)) |
| `user` | string | Wem das Dokument gehört ([Nutzer](#nutzer)) |
| `seq` | integer | Ihre Versionsnummer, 0 bis 2^53; ein niedrigeres `seq` als das gespeicherte wird übersprungen |
| `if_version` | integer | Nur schreiben, wenn die gespeicherte `version` übereinstimmt; `0` schreibt nur ein neues Dokument |

Vollständiges Schema: [Dokumente hinzufügen](https://docs.conare.ai/de/api-reference/documents/add-documents.md).

## Antwort

| Feld | Bedeutung |
| - | - |
| `ids`, `versions` | Id und Version jedes Dokuments, in Anfragereihenfolge |
| `results[].result` | `created`, `updated`, `unchanged` (gleicher Text, gleiche Metadaten und gleicher Nutzer) oder `stale` (ein höheres `seq` ist gespeichert) |
| `results[].chunks` | Passagen, die das Dokument hat |
| `results[].chunks_embedded` | Passagen, die dieser Schreibvorgang eingebettet hat; unveränderte werden nicht erneut eingebettet |
| `results[].stored_seq` | Bei `stale` das gespeicherte `seq` |

Eine `if_version`-Abweichung gibt `409 version_conflict` zurück.

## Metadaten

```json theme={null}
{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }
```

| Regel | Limit |
| - | - |
| Werte | Strings, Zahlen, Booleans oder Arrays von Strings |
| Schlüssel | Bis zu 32, jeweils 1-64 Zeichen aus `A-Z a-z 0-9 _ . -`, beginnend mit einem Buchstaben |
| Reservierte Schlüssel | `id`, `text`, `vector`, `ttl_at_ms` |
| Ein String | Bis zu 4 KiB |
| Ein Array | Bis zu 256 Strings |
| Unterschiedliche Werte pro Dokument | Insgesamt 256: Eine Zahl oder ein String bis 222 Bytes zählt zwei; ein Array-Element, ein Boolean oder ein längerer String eins; ein `user` eins, plus eins pro `:` |

## Nutzer

Setzen Sie `user`, wenn ein Namespace Dokumente vieler Nutzer enthält, und [suchen](https://docs.conare.ai/de/query.md) Sie dann mit `user` oder `user_prefix`.

| Regel | |
| - | - |
| Format | Bis zu 128 Zeichen aus `A-Z a-z 0-9 . _ : @ -`, beginnend mit einem Buchstaben oder einer Ziffer, höchstens 8 `:` |
| Gruppen | Schreiben Sie `tenant-7:u_42` und suchen Sie mit `user_prefix: "tenant-7:"` den gesamten Mandanten |
| Filter | Ein [Filter](https://docs.conare.ai/de/filters.md) kann nicht auf `user` passen; verwenden Sie `user` und `user_prefix` |

## Durchsatz

* Wenn das Embedding ausgelastet ist, wartet ein Schreibvorgang und gibt `Conare-Degraded: embed-busy` zurück: Senden Sie weniger Schreibvorgänge gleichzeitig.
* Nach etwa 30 Sekunden gibt er `503` mit `Retry-After` zurück.
* Eine fehlgeschlagene Anfrage hat möglicherweise einige Dokumente geschrieben: Wiederholen Sie sie mit demselben [`Idempotency-Key`](https://docs.conare.ai/de/api#wiederholungen).


## Related topics

- [Einführung](https://docs.conare.ai/de/index.md)
- [API-Übersicht](https://docs.conare.ai/de/api.md)
- [Namespaces](https://docs.conare.ai/de/namespaces.md)
- [Filter](https://docs.conare.ai/de/filters.md)
- [Suche](https://docs.conare.ai/de/query.md)


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