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

# Busca

> Encontre os trechos que respondem a uma pergunta, por significado e palavra-chave, com reranking.

`POST /namespaces/:namespace/query`

Pesquise um namespace por significado e por palavra-chave; o Conare reranqueia as melhores correspondências e retorna, para cada documento, os trechos que respondem.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'
```

```ts TypeScript theme={null}
const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});
```

```json Response theme={null}
{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}
```

## Opções

| Opção | Tipo | O que faz |
| - | - | - |
| `query` | string, obrigatório | A pergunta, até 8.000 caracteres |
| `top_k` | integer, padrão 10 | Resultados a retornar, 1-500 |
| `filter` | object | Um [filtro de metadados](https://docs.conare.ai/pt-BR/filters.md) |
| `user` | string | Apenas os documentos [deste usuário](https://docs.conare.ai/pt-BR/write.md#usuários) |
| `user_prefix` | string | Apenas usuários que começam com isto, como `tenant-7:` |
| `answer` | boolean, padrão `false` | Também [escreve uma resposta](#respostas) |
| `rerank` | boolean, padrão `true` | Reranqueia as melhores correspondências; `false` é mais rápido |
| `rerank_depth` | integer, padrão 20 | Melhores trechos a reranquear, 1-1.000 |
| `hops` | integer, padrão 1 | `2` pesquisa de novo a partir dos melhores resultados ([dois saltos](#dois-saltos)) |
| `retrievers` | array, padrão `["vector", "keyword"]` | 1 ou 2 entre `vector` (significado) e `keyword` |
| `exclude_ids` | array | Até 10.000 ids de documento a excluir |
| `max_results` | integer | [Pagine](#páginas) por até 1.000 resultados, ou 5.000 com um modelo personalizado |
| `cursor` | string | O `next_cursor` da página anterior |

Schema completo: [Consultar um namespace](https://docs.conare.ai/pt-br/api-reference/query/query-a-namespace.md).

## Resposta

| Campo | Significado |
| - | - |
| `results` | Do melhor para o pior, um por documento |
| `results[].id`, `metadata`, `user` | Os do documento |
| `results[].text` | Seus trechos que respondem, do melhor para o pior: o melhor e até mais dois que correspondem quase tão bem, cada um com até cerca de 3.000 bytes, com uma linha contendo apenas `…` entre trechos que não são consecutivos; [obtenha o documento](https://docs.conare.ai/pt-BR/documents.md) para vê-lo inteiro |
| `results[].score` | Maior é melhor; compare apenas dentro de uma mesma consulta |
| `results[].reranked` | Se o reranker o pontuou; resultados não reranqueados vêm por último |
| `answer` | A resposta, com `answer: true` |
| `next_cursor` | Com `max_results`, o `cursor` da próxima página; omitido na última página |
| `took_ms` | Tempo de busca em milissegundos |

## Respostas

`"answer": true` adiciona uma resposta escrita a partir dos melhores trechos, em cerca de 2 segundos a mais.

```json Response theme={null}
{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}
```

* Um modelo de linguagem a escreve a partir dos trechos encontrados; veja a [política de privacidade](https://conare.ai/privacy).
* Se esse modelo estiver indisponível, você recebe os resultados sem `answer`.

## Dois saltos

`"hops": 2` pesquisa de novo a partir dos melhores resultados, para perguntas cuja resposta exige fatos de dois documentos.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'
```

* Adiciona cerca de 0,3 segundo: use-o para perguntas que encadeiam fatos.
* Retorna `400 invalid_request` com `rerank: false`, com `max_results` e em namespaces de um modelo personalizado.

## Páginas

| Etapa | Envie |
| - | - |
| Primeira página | `query`, `max_results` (quantos ranquear de uma vez) e `top_k` (tamanho da página) |
| Próximas páginas | Apenas `cursor` (o último `next_cursor`) e `top_k` |
| Última página | Não tem `next_cursor` |

Um cursor dura 15 minutos. O `queryPages()` do SDK lê todas as páginas.

## Pesquisar todos os namespaces

`POST /query`

A mesma requisição em até 100 namespaces, reranqueados juntos; `prefix` se limita aos namespaces cujos nomes começam com ele.

```bash curl theme={null}
curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'
```

```json Response theme={null}
{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}
```

| Opção ou campo | Aqui |
| - | - |
| `prefix` | Apenas namespaces cujos nomes começam com isto |
| `rerank_depth` | Padrão 60, 1-1.000 |
| `exclude_ids` | Escritos como `namespace/id` |
| `results[].namespace` | O namespace do resultado |
| `namespaces`, `skipped_namespaces` | Os pesquisados e os que passaram dos 100 primeiros |

`hops` também funciona aqui. Schema completo: [Consultar todos os namespaces](https://docs.conare.ai/pt-br/api-reference/query/query-every-namespace.md).

## Resultados degradados

Se parte de uma busca falhar, a consulta ainda é bem-sucedida e o cabeçalho `Conare-Degraded` informa o que foi ignorado.

| Valor | Significado |
| - | - |
| `rerank`, `rerank-partial` | Alguns ou todos os resultados não foram reranqueados (`reranked: false`) |
| `embed` | Pesquisado apenas por palavra-chave |
| `keyword`, `keyword-terms` | A consulta era longa demais para a busca por palavra-chave lê-la inteira |
| `embed-next` | Parte do namespace não pôde ser pesquisada |
| `cursor` | Sem `next_cursor`; pesquise de novo para obter mais páginas |
| `embed-busy`, `embed-fallback` | Mais lento que o normal; os resultados não são afetados |
| `answer` | Sem resposta, apenas resultados |

Se nada puder pesquisar, a consulta retorna `503`.


## Related topics

- [Arquivos](https://docs.conare.ai/pt-BR/files.md)
- [Console](https://docs.conare.ai/pt-BR/console.md)
- [Query a namespace](https://docs.conare.ai/pt-br/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/pt-br/api-reference/query/query-every-namespace.md)
- [SDK TypeScript](https://docs.conare.ai/pt-BR/sdk.md)


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