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

# Ricerca

> Trova i passaggi che rispondono a una domanda, per significato e parola chiave, con reranking.

`POST /namespaces/:namespace/query`

Cerca in un namespace per significato e per parola chiave; Conare riordina le corrispondenze migliori e restituisce, per ogni documento, i passaggi che rispondono.

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

## Opzioni

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `query` | string, obbligatorio | La domanda, fino a 8.000 caratteri |
| `top_k` | integer, predefinito 10 | Risultati da restituire, 1-500 |
| `filter` | object | Un [filtro sui metadati](https://docs.conare.ai/it/filters.md) |
| `user` | string | Solo i documenti di questo [utente](https://docs.conare.ai/it/write.md#utenti) |
| `user_prefix` | string | Solo gli utenti che iniziano così, come `tenant-7:` |
| `answer` | boolean, predefinito `false` | [Scrive anche una risposta](#risposte) |
| `rerank` | boolean, predefinito `true` | Riordina le corrispondenze migliori; `false` è più veloce |
| `rerank_depth` | integer, predefinito 20 | Passaggi migliori da riordinare, 1-1.000 |
| `hops` | integer, predefinito 1 | `2` cerca di nuovo a partire dai risultati migliori ([due passaggi](#due-passaggi)) |
| `retrievers` | array, predefinito `["vector", "keyword"]` | 1 o 2 tra `vector` (significato) e `keyword` |
| `exclude_ids` | array | Fino a 10.000 id di documenti da escludere |
| `max_results` | integer | Scorri per [pagine](#pagine) fino a 1.000 risultati, o 5.000 con un modello personalizzato |
| `cursor` | string | Il `next_cursor` della pagina precedente |

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

## Risposta

| Campo | Significato |
| - | - |
| `results` | Prima i migliori, uno per documento |
| `results[].id`, `metadata`, `user` | Quelli del documento |
| `results[].text` | I suoi passaggi che rispondono, il migliore per primo: il migliore e fino ad altri due quasi altrettanto pertinenti, ciascuno fino a circa 3.000 byte, con una riga contenente solo `…` tra passaggi non consecutivi; [recupera il documento](https://docs.conare.ai/it/documents.md) per averlo tutto |
| `results[].score` | Più alto è meglio; confrontalo solo all'interno di una query |
| `results[].reranked` | Se il reranker gli ha assegnato un punteggio; i risultati non riordinati vengono per ultimi |
| `answer` | La risposta, con `answer: true` |
| `next_cursor` | Con `max_results`, il `cursor` della pagina successiva; assente nell'ultima pagina |
| `took_ms` | Tempo di ricerca in millisecondi |

## Risposte

`"answer": true` aggiunge una risposta scritta dai passaggi migliori, in circa 2 secondi in più.

```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 modello linguistico la scrive dai passaggi trovati; vedi l'[informativa sulla privacy](https://conare.ai/privacy).
* Se quel modello non è disponibile, ricevi i risultati senza `answer`.

## Due passaggi

`"hops": 2` cerca di nuovo a partire dai risultati migliori, per domande la cui risposta richiede fatti da due documenti.

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

* Aggiunge circa 0,3 secondi: usalo per domande che concatenano fatti.
* Restituisce `400 invalid_request` con `rerank: false`, con `max_results` e sui namespace di un modello personalizzato.

## Pagine

| Passo | Invia |
| - | - |
| Prima pagina | `query`, `max_results` (quanti classificarne una volta) e `top_k` (dimensione della pagina) |
| Pagine successive | Solo `cursor` (l'ultimo `next_cursor`) e `top_k` |
| Ultima pagina | Non ha `next_cursor` |

Un cursore dura 15 minuti. Il metodo `queryPages()` dell'SDK legge tutte le pagine.

## Cercare in tutti i namespace

`POST /query`

La stessa richiesta su un massimo di 100 namespace, riordinati insieme; `prefix` limita ai namespace il cui nome inizia con esso.

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

| Opzione o campo | Qui |
| - | - |
| `prefix` | Solo i namespace il cui nome inizia con questo |
| `rerank_depth` | Predefinito 60, 1-1.000 |
| `exclude_ids` | Scritti come `namespace/id` |
| `results[].namespace` | Il namespace del risultato |
| `namespaces`, `skipped_namespaces` | Quelli cercati, e quelli oltre i primi 100 |

Anche `hops` funziona qui. Schema completo: [Query every namespace](https://docs.conare.ai/it/api-reference/query/query-every-namespace.md).

## Risultati degradati

Se una parte della ricerca fallisce, la query riesce comunque e l'header `Conare-Degraded` indica cosa è stato saltato.

| Valore | Significato |
| - | - |
| `rerank`, `rerank-partial` | Alcuni o tutti i risultati non sono stati riordinati (`reranked: false`) |
| `embed` | Ricerca solo per parola chiave |
| `keyword`, `keyword-terms` | La query era troppo lunga perché la ricerca per parola chiave la leggesse tutta |
| `embed-next` | Non è stato possibile cercare in una parte del namespace |
| `cursor` | Nessun `next_cursor`; cerca di nuovo per altre pagine |
| `embed-busy`, `embed-fallback` | Più lento del solito; i risultati non ne risentono |
| `answer` | Nessuna risposta, solo risultati |

Se non è stato possibile cercare nulla, la query restituisce `503`.


## Related topics

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


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