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

# Búsqueda

> Encuentra los pasajes que responden a una pregunta, por significado y palabra clave, con reranking.

`POST /namespaces/:namespace/query`

Busca en un namespace por significado y por palabra clave; Conare aplica reranking a las mejores coincidencias y devuelve, para cada documento, los pasajes que responden.

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

## Opciones

| Opción | Tipo | Qué hace |
| - | - | - |
| `query` | string, obligatorio | La pregunta, hasta 8.000 caracteres |
| `top_k` | integer, predeterminado 10 | Resultados que devolver, de 1 a 500 |
| `filter` | object | Un [filtro de metadatos](https://docs.conare.ai/es/filters.md) |
| `user` | string | Solo los documentos de este [usuario](https://docs.conare.ai/es/write.md#usuarios) |
| `user_prefix` | string | Solo los usuarios que empiezan así, como `tenant-7:` |
| `answer` | boolean, predeterminado `false` | Además, [redacta una respuesta](#respuestas) |
| `rerank` | boolean, predeterminado `true` | Aplica reranking a las mejores coincidencias; `false` es más rápido |
| `rerank_depth` | integer, predeterminado 20 | Pasajes principales a los que aplicar reranking, de 1 a 1.000 |
| `hops` | integer, predeterminado 1 | `2` vuelve a buscar a partir de los mejores resultados ([dos saltos](#dos-saltos)) |
| `retrievers` | array, predeterminado `["vector", "keyword"]` | 1 o 2 de `vector` (significado) y `keyword` |
| `exclude_ids` | array | Hasta 10.000 ids de documentos que excluir |
| `max_results` | integer | [Pagina](#páginas) hasta 1.000 resultados, o 5.000 con un modelo personalizado |
| `cursor` | string | El `next_cursor` de la página anterior |

Esquema completo: [Query a namespace](https://docs.conare.ai/es/api-reference/query/query-a-namespace.md).

## Respuesta

| Campo | Significado |
| - | - |
| `results` | El mejor primero, uno por documento |
| `results[].id`, `metadata`, `user` | Los del documento |
| `results[].text` | Sus pasajes que responden, del mejor al peor: el mejor y hasta dos más que coinciden casi igual de bien, cada uno de hasta unos 3.000 bytes, con una línea que solo contiene `…` entre pasajes que no son consecutivos; [obtén el documento](https://docs.conare.ai/es/documents.md) para tenerlo completo |
| `results[].score` | Cuanto más alto, mejor; compáralo solo dentro de una misma consulta |
| `results[].reranked` | Si el reranker lo puntuó; los resultados sin reranking van al final |
| `answer` | La respuesta, con `answer: true` |
| `next_cursor` | Con `max_results`, el `cursor` de la página siguiente; se omite en la última página |
| `took_ms` | Tiempo de búsqueda en milisegundos |

## Respuestas

`"answer": true` añade una respuesta redactada a partir de los mejores pasajes, en unos 2 segundos más.

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

* Un modelo de lenguaje la redacta a partir de los pasajes encontrados; consulta la [política de privacidad](https://conare.ai/privacy).
* Si ese modelo no está disponible, recibes los resultados sin `answer`.

## Dos saltos

`"hops": 2` vuelve a buscar a partir de los mejores resultados, para preguntas cuya respuesta necesita datos de dos 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}'
```

* Añade unos 0,3 segundos: úsalo para preguntas que encadenan datos.
* Devuelve `400 invalid_request` con `rerank: false`, con `max_results` y en namespaces de un modelo personalizado.

## Páginas

| Paso | Envía |
| - | - |
| Primera página | `query`, `max_results` (cuántos clasificar una vez) y `top_k` (tamaño de página) |
| Páginas siguientes | Solo `cursor` (el último `next_cursor`) y `top_k` |
| Última página | No tiene `next_cursor` |

Un cursor dura 15 minutos. El `queryPages()` del SDK lee todas las páginas.

## Buscar en todos los namespaces

`POST /query`

La misma solicitud en hasta 100 namespaces, con reranking conjunto; `prefix` se limita a los namespaces cuyo nombre empieza por él.

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

| Opción o campo | Aquí |
| - | - |
| `prefix` | Solo los namespaces cuyo nombre empieza así |
| `rerank_depth` | Predeterminado 60, de 1 a 1.000 |
| `exclude_ids` | Se escriben como `namespace/id` |
| `results[].namespace` | El namespace del resultado |
| `namespaces`, `skipped_namespaces` | Los buscados, y los que quedan después de los 100 primeros |

`hops` también funciona aquí. Esquema completo: [Query every namespace](https://docs.conare.ai/es/api-reference/query/query-every-namespace.md).

## Resultados degradados

Si falla parte de una búsqueda, la consulta sigue teniendo éxito y la cabecera `Conare-Degraded` indica qué se omitió.

| Valor | Significado |
| - | - |
| `rerank`, `rerank-partial` | Algunos o todos los resultados no tuvieron reranking (`reranked: false`) |
| `embed` | Búsqueda solo por palabra clave |
| `keyword`, `keyword-terms` | La consulta era demasiado larga para que la búsqueda por palabra clave la leyera entera |
| `embed-next` | No se pudo buscar en parte del namespace |
| `cursor` | Sin `next_cursor`; vuelve a buscar para obtener más páginas |
| `embed-busy`, `embed-fallback` | Más lento de lo habitual; los resultados no se ven afectados |
| `answer` | Sin respuesta, solo resultados |

Si no se pudo buscar nada, la consulta devuelve `503`.


## Related topics

- [Consola](https://docs.conare.ai/es/console.md)
- [Query a namespace](https://docs.conare.ai/es/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/es/api-reference/query/query-every-namespace.md)
- [Google Cloud Storage](https://docs.conare.ai/es/gcs.md)
- [Filtros](https://docs.conare.ai/es/filters.md)


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