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

# Query

> Find the passages that answer a question.

`POST /namespaces/:namespace/query`

Searches one namespace by meaning and by keyword, reranks the best matches, and returns each
matching document's best passage.

<CodeGroup>
  ```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" },
  });
  ```
</CodeGroup>

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

## Request

* `query` (string, required): What to search for, in plain language. Up to 8,000 characters.
* `top_k` (integer, default 10): Results to return, 1-100.
* `filter` (object): A [metadata filter](/filters).
* `rerank` (boolean, default `true`): Rerank the best matches. `false` is faster.
* `rerank_depth` (integer, default 20): How many of the top passages to rerank, 1-100.
* `retrievers` (array, default `["vector", "keyword"]`): The [retrievers](#retrievers) to combine.
* `user` (string): Only this [user's](#users) documents.
* `user_prefix` (string): Only the documents of the [users](#users) that start with it, such as
  `tenant-7:`. It ends with `:`.

## Response

* `results`: Best first, one per document.
  * `id`, `metadata`: The document's.
  * `text`: The document's best matching passage, up to about 2,000 bytes. [Get the
    document](/documents#get-a-document) for its full text.
  * `score`: Higher is better. Reranked and unreranked scores aren't comparable, and neither
    compares across queries.
  * `reranked`: Whether the reranker scored this result. Results past `rerank_depth` aren't
    reranked, and come after those that are.
  * `user`: The document's [user](/write#users). Left out if it has none.
* `took_ms`: Time spent searching, in milliseconds.

## Retrievers

| Retriever | Finds |
| - | - |
| `vector` | Passages close in meaning to the query |
| `keyword` | Passages with the query's words (BM25) |
| `sparse` | Passages with the query's words or related ones (SPLADE). Needs a namespace with a [sparse index](/namespaces#sparse-index). |

Conare fuses their rankings with reciprocal rank fusion, weighted equally.

## Users

Keep a search to the documents [written for a user](/write#users) with `user`, or to a group of
users with `user_prefix`:

<CodeGroup>
  ```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": "refund requests", "user_prefix": "tenant-7:"}'
  ```

  ```ts TypeScript theme={null}
  const results = await docs.query("refund requests", { userPrefix: "tenant-7:" });
  ```
</CodeGroup>

* `user_prefix: "tenant-7:"` matches `tenant-7:u_42` and `tenant-7:team-a:u_7`, but not `tenant-7`.
* `user`, `user_prefix` and `filter` combine: a result matches all of them.

## Search every namespace

`POST /query`

Takes the same body, plus `prefix` to search only namespaces whose names start with it. Searches up
to 100 namespaces, the first in name order, and reranks their results together.

```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}
{
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.34,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "namespaces": ["acme-docs", "acme-tickets"],
  "skipped_namespaces": [],
  "took_ms": 43
}
```

* Each result names its `namespace`. A passage repeated in two namespaces appears once.
* `namespaces` lists the namespaces searched, and `skipped_namespaces` those past the first 100.
* A **Some namespaces** key searches only its own namespaces.
* `rerank_depth` defaults to 100.
* The SDK has no method for this route yet.

## Degraded results

When part of a search fails, the query still succeeds, and the `Conare-Degraded` header lists what
happened:

| Value | Meaning |
| - | - |
| `rerank` | Reranking failed. Results are in retrieval order, with `reranked: false`. |
| `embed` | The query couldn't be embedded. Searched without `vector`. |
| `sparse` | The query couldn't be encoded for `sparse`. Searched without it. |
| `embed-fallback` | A backup copy of the embedding model answered. Results are unaffected. |

If no retriever is left, the query returns `503 unavailable`.

## Behavior

* Querying an empty or missing namespace returns `404 namespace_not_found`.
* A repeated query reuses its embedding for up to 10 minutes, so measure latency with distinct
  queries.


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