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

# Escribir documentos

> Añade o reemplaza hasta 100 documentos en un namespace; se pueden buscar en cuanto la llamada responde.

`POST /namespaces/:namespace/documents`

Escribe documentos en un namespace: Conare los divide en fragmentos, los embebe y los indexa, y la primera escritura crea el 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]
}
```

## Opciones

| Opción | Tipo | Qué hace |
| - | - | - |
| `documents` | array, obligatorio | De 1 a 100 documentos |
| `id` | string | Hasta 256 caracteres de `A-Z a-z 0-9 . _ : -`; se genera si se omite. Escribir un id existente lo reemplaza |
| `text` | string, obligatorio | Cualquier longitud dentro del cuerpo de 32 MiB de la petición; un texto largo sigue siendo un documento |
| `metadata` | object | Valores por los que [filtrar](https://docs.conare.ai/es/filters.md) ([reglas](#metadatos)) |
| `user` | string | A quién pertenece el documento ([usuarios](#usuarios)) |
| `seq` | integer | Tu número de versión, de 0 a 2^53; un `seq` inferior al almacenado se omite |
| `if_version` | integer | Escribe solo si la `version` almacenada coincide; `0` escribe solo un documento nuevo |

Esquema completo: [Añadir documentos](https://docs.conare.ai/es/api-reference/documents/add-documents.md).

## Respuesta

| Campo | Significado |
| - | - |
| `ids`, `versions` | El id y la versión de cada documento, en el orden de la solicitud |
| `results[].result` | `created`, `updated`, `unchanged` (mismo texto, metadatos y usuario) o `stale` (hay un `seq` mayor almacenado) |
| `results[].chunks` | Pasajes que tiene el documento |
| `results[].chunks_embedded` | Pasajes que embebió esta escritura; los que no cambian no se vuelven a embeber |
| `results[].stored_seq` | Con `stale`, el `seq` almacenado |

Si `if_version` no coincide, se devuelve `409 version_conflict`.

## Metadatos

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

| Regla | Límite |
| - | - |
| Valores | Strings, números, booleanos o arrays de strings |
| Claves | Hasta 32, cada una de 1-64 caracteres de `A-Z a-z 0-9 _ . -`, empezando por una letra |
| Claves reservadas | `id`, `text`, `vector`, `ttl_at_ms` |
| Un string | Hasta 4 KiB |
| Un array | Hasta 256 strings |
| Valores distintos por documento | 256 en total: un número o un string de hasta 222 bytes cuenta dos; un elemento de array, un booleano o un string más largo, uno; un `user`, uno, más uno por cada `:` |

## Usuarios

Define `user` cuando un namespace contiene documentos de muchos usuarios, y luego [busca](https://docs.conare.ai/es/query.md) con `user` o `user_prefix`.

| Regla | |
| - | - |
| Formato | Hasta 128 caracteres de `A-Z a-z 0-9 . _ : @ -`, empezando por una letra o un dígito, con 8 `:` como máximo |
| Grupos | Escribe `tenant-7:u_42` y busca `user_prefix: "tenant-7:"` para todo el tenant |
| Filtros | Un [filtro](https://docs.conare.ai/es/filters.md) no puede coincidir con `user`; usa `user` y `user_prefix` |

## Rendimiento

* Cuando el embedding está ocupado, una escritura espera y devuelve `Conare-Degraded: embed-busy`: envía menos escrituras a la vez.
* Tras unos 30 segundos devuelve `503` con `Retry-After`.
* Una solicitud fallida puede haber escrito algunos documentos: reinténtala con la misma [`Idempotency-Key`](https://docs.conare.ai/es/api#reintentos).


## Related topics

- [Introducción](https://docs.conare.ai/es/index.md)
- [Consola](https://docs.conare.ai/es/console.md)
- [Obtener, listar y eliminar documentos](https://docs.conare.ai/es/documents.md)
- [MCP](https://docs.conare.ai/es/mcp-server.md)
- [Filtros](https://docs.conare.ai/es/filters.md)


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