Ricerca

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.

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
}

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
`user`	string	Solo i documenti di questo utente
`user_prefix`	string	Solo gli utenti che iniziano così, come `tenant-7:`
`answer`	boolean, predefinito `false`	Scrive anche una risposta
`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)
`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 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.

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

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
}

Un modello linguistico la scrive dai passaggi trovati; vedi l’informativa sulla 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.

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

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.

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
}

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.

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.

Primi passi

Fondamenti

File

Sincronizzazione

Modelli

Strumenti

Opzioni

Risposta

Risposte

Due passaggi

Pagine

Cercare in tutti i namespace

Risultati degradati

​Opzioni

​Risposta

​Risposte

​Due passaggi

​Pagine

​Cercare in tutti i namespace

​Risultati degradati

Opzioni

Risposta

Risposte

Due passaggi

Pagine

Cercare in tutti i namespace

Risultati degradati