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

# Recherche

> Trouvez les passages qui répondent à une question, par sens et par mot-clé, avec reranking.

`POST /namespaces/:namespace/query`

Recherchez dans un namespace par sens et par mot-clé ; Conare reranke les meilleures correspondances et renvoie, pour chaque document, les passages qui répondent.

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

## Options

| Option | Type | Ce qu'elle fait |
| - | - | - |
| `query` | chaîne, requis | La question, jusqu'à 8 000 caractères |
| `top_k` | entier, 10 par défaut | Résultats à renvoyer, de 1 à 500 |
| `filter` | objet | Un [filtre de métadonnées](https://docs.conare.ai/fr/filters.md) |
| `user` | chaîne | Uniquement les documents de cet [utilisateur](https://docs.conare.ai/fr/write.md#utilisateurs) |
| `user_prefix` | chaîne | Uniquement les utilisateurs commençant par cette valeur, comme `tenant-7:` |
| `answer` | booléen, `false` par défaut | [Rédige aussi une réponse](#réponses) |
| `rerank` | booléen, `true` par défaut | Reranke les meilleures correspondances ; `false` est plus rapide |
| `rerank_depth` | entier, 20 par défaut | Nombre de meilleurs passages à reranker, de 1 à 1 000 |
| `hops` | entier, 1 par défaut | `2` relance une recherche à partir des meilleurs résultats ([deux sauts](#deux-sauts)) |
| `retrievers` | tableau, `["vector", "keyword"]` par défaut | 1 ou 2 parmi `vector` (sens) et `keyword` |
| `exclude_ids` | tableau | Jusqu'à 10 000 ids de documents à exclure |
| `max_results` | entier | [Parcourir par pages](#pages) jusqu'à 1 000 résultats, ou 5 000 avec un modèle personnalisé |
| `cursor` | chaîne | Le `next_cursor` de la page précédente |

Schéma complet : [Query a namespace](https://docs.conare.ai/fr/api-reference/query/query-a-namespace.md).

## Réponse

| Champ | Signification |
| - | - |
| `results` | Le meilleur en premier, un par document |
| `results[].id`, `metadata`, `user` | Ceux du document |
| `results[].text` | Ses passages qui répondent, du meilleur au moins bon : le meilleur et jusqu'à deux autres presque aussi pertinents, chacun jusqu'à environ 3 000 octets, avec une ligne contenant seulement `…` entre les passages qui ne se suivent pas ; [récupérez le document](https://docs.conare.ai/fr/documents.md) pour l'avoir en entier |
| `results[].score` | Plus il est élevé, mieux c'est ; comparez uniquement au sein d'une même requête |
| `results[].reranked` | Indique si le reranker l'a noté ; les résultats non rerankés arrivent en dernier |
| `answer` | La réponse, avec `answer: true` |
| `next_cursor` | Avec `max_results`, le `cursor` de la page suivante ; absent sur la dernière page |
| `took_ms` | Durée de la recherche en millisecondes |

## Réponses

`"answer": true` ajoute une réponse rédigée à partir des meilleurs passages, en environ 2 secondes de plus.

```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 modèle de langage la rédige à partir des passages trouvés ; voir la [politique de confidentialité](https://conare.ai/privacy).
* Si ce modèle est indisponible, vous obtenez les résultats sans `answer`.

## Deux sauts

`"hops": 2` relance une recherche à partir des meilleurs résultats, pour les questions dont la réponse nécessite des faits issus de deux documents.

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

* Cela ajoute environ 0,3 seconde : utilisez-le pour les questions qui enchaînent des faits.
* Renvoie `400 invalid_request` avec `rerank: false`, avec `max_results` et sur les namespaces d'un modèle personnalisé.

## Pages

| Étape | À envoyer |
| - | - |
| Première page | `query`, `max_results` (combien classer en une fois) et `top_k` (taille de page) |
| Pages suivantes | Uniquement `cursor` (le dernier `next_cursor`) et `top_k` |
| Dernière page | N'a pas de `next_cursor` |

Un curseur dure 15 minutes. La méthode `queryPages()` du SDK lit toutes les pages.

## Rechercher dans tous les namespaces

`POST /query`

La même requête sur jusqu'à 100 namespaces, rerankés ensemble ; `prefix` se limite aux namespaces dont le nom commence par cette valeur.

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

| Option ou champ | Ici |
| - | - |
| `prefix` | Uniquement les namespaces dont le nom commence par cette valeur |
| `rerank_depth` | 60 par défaut, de 1 à 1 000 |
| `exclude_ids` | Écrits sous la forme `namespace/id` |
| `results[].namespace` | Le namespace du résultat |
| `namespaces`, `skipped_namespaces` | Ceux recherchés, et ceux au-delà des 100 premiers |

`hops` fonctionne ici aussi. Schéma complet : [Query every namespace](https://docs.conare.ai/fr/api-reference/query/query-every-namespace.md).

## Résultats dégradés

Si une partie d'une recherche échoue, la requête réussit quand même et l'en-tête `Conare-Degraded` indique ce qui a été ignoré.

| Valeur | Signification |
| - | - |
| `rerank`, `rerank-partial` | Une partie ou la totalité des résultats n'a pas été rerankée (`reranked: false`) |
| `embed` | Recherche par mot-clé uniquement |
| `keyword`, `keyword-terms` | La requête était trop longue pour que la recherche par mot-clé la lise en entier |
| `embed-next` | Une partie du namespace n'a pas pu être recherchée |
| `cursor` | Pas de `next_cursor` ; relancez la recherche pour d'autres pages |
| `embed-busy`, `embed-fallback` | Plus lent que d'habitude ; les résultats ne sont pas affectés |
| `answer` | Pas de réponse, uniquement les résultats |

Si aucune recherche n'a pu s'exécuter, la requête renvoie `503`.


## Related topics

- [Query a namespace](https://docs.conare.ai/fr/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/fr/api-reference/query/query-every-namespace.md)
- [Embedding et reranking](https://docs.conare.ai/fr/embed-rerank.md)
- [SDK TypeScript](https://docs.conare.ai/fr/sdk.md)
- [Filtres](https://docs.conare.ai/fr/filters.md)


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