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

# Gravar documentos

> Adicione ou substitua até 100 documentos em um namespace; eles podem ser buscados assim que a chamada retorna.

`POST /namespaces/:namespace/documents`

Grave documentos em um namespace: a Conare os divide em chunks, gera embeddings e os indexa, e a primeira gravação cria o 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]
}
```

## Opções

| Opção | Tipo | O que faz |
| - | - | - |
| `documents` | array, obrigatório | De 1 a 100 documentos |
| `id` | string | Até 256 caracteres de `A-Z a-z 0-9 . _ : -`; gerado se omitido. Gravar um id existente o substitui |
| `text` | string, obrigatório | Qualquer tamanho dentro do corpo de 32 MiB da requisição; um texto longo continua sendo um documento |
| `metadata` | object | Valores para [filtrar](https://docs.conare.ai/pt-BR/filters.md) ([regras](#metadados)) |
| `user` | string | A quem o documento pertence ([usuários](#usuários)) |
| `seq` | integer | Seu número de versão, de 0 a 2^53; um `seq` menor que o armazenado é ignorado |
| `if_version` | integer | Grava só se a `version` armazenada coincidir; `0` grava só um documento novo |

Schema completo: [Adicionar documentos](https://docs.conare.ai/pt-br/api-reference/documents/add-documents.md).

## Resposta

| Campo | Significado |
| - | - |
| `ids`, `versions` | O id e a versão de cada documento, na ordem da requisição |
| `results[].result` | `created`, `updated`, `unchanged` (mesmo texto, metadados e usuário) ou `stale` (um `seq` maior está armazenado) |
| `results[].chunks` | Trechos que o documento tem |
| `results[].chunks_embedded` | Trechos com embedding gerado nesta gravação; os inalterados não são processados de novo |
| `results[].stored_seq` | Com `stale`, o `seq` armazenado |

Uma divergência de `if_version` retorna `409 version_conflict`.

## Metadados

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

| Regra | Limite |
| - | - |
| Valores | Strings, números, booleanos ou arrays de strings |
| Chaves | Até 32, cada uma com 1-64 caracteres de `A-Z a-z 0-9 _ . -`, começando com uma letra |
| Chaves reservadas | `id`, `text`, `vector`, `ttl_at_ms` |
| Uma string | Até 4 KiB |
| Um array | Até 256 strings |
| Valores distintos por documento | 256 no total: um número ou uma string de até 222 bytes conta dois; um item de array, um booleano ou uma string mais longa, um; um `user`, um, mais um por `:` |

## Usuários

Defina `user` quando um namespace guarda documentos de muitos usuários e depois [busque](https://docs.conare.ai/pt-BR/query.md) com `user` ou `user_prefix`.

| Regra | |
| - | - |
| Formato | Até 128 caracteres de `A-Z a-z 0-9 . _ : @ -`, começando com uma letra ou dígito, no máximo 8 `:` |
| Grupos | Grave `tenant-7:u_42` e busque `user_prefix: "tenant-7:"` para o tenant inteiro |
| Filtros | Um [filtro](https://docs.conare.ai/pt-BR/filters.md) não pode corresponder a `user`; use `user` e `user_prefix` |

## Throughput

* Quando a geração de embeddings está ocupada, uma gravação espera e retorna `Conare-Degraded: embed-busy`: envie menos gravações ao mesmo tempo.
* Após cerca de 30 segundos, ela retorna `503` com `Retry-After`.
* Uma requisição com falha pode ter gravado alguns documentos: repita-a com o mesmo [`Idempotency-Key`](https://docs.conare.ai/pt-BR/api#novas-tentativas).


## Related topics

- [Console](https://docs.conare.ai/pt-BR/console.md)
- [Obter, listar e excluir documentos](https://docs.conare.ai/pt-BR/documents.md)
- [MCP](https://docs.conare.ai/pt-BR/mcp-server.md)
- [Filtros](https://docs.conare.ai/pt-BR/filters.md)
- [Google Cloud Storage](https://docs.conare.ai/pt-BR/gcs.md)


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