Busca

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.

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"}}'

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

Response

{
  "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
`user`	string	Apenas os documentos deste usuário
`user_prefix`	string	Apenas usuários que começam com isto, como `tenant-7:`
`answer`	boolean, padrão `false`	Também escreve uma resposta
`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)
`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 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.

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

Response

{
  "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.
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.

curl

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.

curl

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-"}'

Response

{
  "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.

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.

Primeiros passos

Essencial

Arquivos

Sincronização

Modelos

Ferramentas

Opções

Resposta

Respostas

Dois saltos

Páginas

Pesquisar todos os namespaces

Resultados degradados

​Opções

​Resposta

​Respostas

​Dois saltos

​Páginas

​Pesquisar todos os namespaces

​Resultados degradados

Opções

Resposta

Respostas

Dois saltos

Páginas

Pesquisar todos os namespaces

Resultados degradados