IntelligenceBox

Riferimento API

Ricerca

Solo il recupero. Mandi una domanda e ricevi i passaggi che la rispondono, con il documento di origine e il numero di pagina — nessuna chiamata al modello, nessun testo generato, nessun costo in token. È lo stesso passo di recupero che l’endpoint di chat esegue al suo interno, esposto perché tu possa costruirci sopra il tuo flusso.

Cercare in una cartella#

POST/api/public/vectors/:id/searchAPI key

Trasforma la domanda in vettori, esegue il recupero ibrido (vettoriale + full-text) sulla cartella e restituisce i passaggi ordinati per pertinenza.

curl -X POST BOX_URL/api/public/vectors/FOLDER_ID/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the notice period for termination?",
    "limit": 5
  }'

Corpo della richiesta

querystringobbligatorio
Che cosa stai cercando, in linguaggio naturale. Massimo 2000 caratteri.
limitinteger
Quanti passaggi restituire, da 1 a 50.Predefinito: 10.
documentIdsstring[]
Limita la ricerca a documenti specifici. Gli ID arrivano dall’endpoint dei file. Massimo 100.

Risposta

JSON
{
  "query": "What is the notice period for termination?",
  "results": [
    {
      "id": "c41f8b02-6d3a-4e19-9f75-2a08b1c6e934",
      "score": 0.8412,
      "text": "Either party may terminate this Agreement upon ninety (90) days' prior written notice…",
      "documentId": "7a2e5c9b-1f40-4d83-b6a1-3c9e0d7f2b58",
      "filePath": "Contracts 2026/acme-msa-2026.pdf",
      "fileName": "acme-msa-2026.pdf",
      "pageNumber": 14,
      "chunkIndex": 3
    }
  ]
}
scorenumber
Pertinenza, più alto è meglio. Confrontabile all’interno di una stessa risposta, non tra domande diverse — non fissare una soglia assoluta nel codice.
textstring
Il passaggio trovato, testuale dal documento.
documentIdstring
Il documento di origine. Usalo per recuperare il file originale o per restringere una ricerca successiva.
fileNamestring
Nome del file di origine, pronto da mostrare in una citazione.
pageNumberinteger
Pagina da cui arriva il passaggio, quando il formato di origine ha pagine.
chunkIndexinteger
Posizione del passaggio all’interno del documento.
  • 200La ricerca è stata eseguita. Un array results vuoto significa che non ha trovato nulla — non è un errore.
  • 400La cartella usa la strategia TABULAR, che si interroga in SQL attraverso la chat invece che semanticamente.
  • 404Cartella inesistente, o il proprietario della chiave non vi ha accesso.

Come funziona l’ordinamento#

Vale la pena saperlo, perché spiega i risultati che ottieni.

  • La domanda usa il modello della cartella stessa. Ogni cartella registra con quale modello è stata indicizzata, e la domanda viene trasformata in vettori con quello stesso modello. È per questo che la ricerca continua a funzionare quando il box passa a un modello più recente: le cartelle vecchie continuano a rispondere correttamente.
  • Il recupero è ibrido. La somiglianza vettoriale trova i passaggi che dicono la stessa cosa; la ricerca full-text intercetta codici prodotto, sigle e nomi esatti che i vettori sfumano. I due risultati vengono fusi in un unico ordinamento.
  • I risultati sono passaggi, non documenti. Lo stesso documento può comparire più volte con valori di chunkIndex diversi. Raggruppa per documentId se vuoi una vista per documento.

Prima cerca, poi chiedi

Un modo di procedere comune è cercare, mostrare i passaggi all’utente per conferma e solo dopo mandare quelli buoni all’endpoint di chat come contesto. Paghi esattamente una chiamata al modello, e l’utente vede su cosa si baserà la risposta prima che venga generata.

Ricette#

Cercare in tutte le cartelle insieme

L’endpoint lavora su una cartella sola. Per cercare ovunque, apri più chiamate in parallelo e unisci i risultati — i punteggi sono abbastanza confrontabili all’interno di una stessa domanda da poterli ordinare tra cartelle diverse.

JavaScript
const { vectors } = await api("/api/public/vectors");

const perFolder = await Promise.all(
  vectors
    .filter((v) => v.strategy !== "TABULAR")
    .map(async (v) => {
      const { results } = await api(`/api/public/vectors/${v.id}/search`, {
        method: "POST",
        body: JSON.stringify({ query, limit: 5 }),
      });
      return results.map((hit) => ({ ...hit, folder: v.name }));
    }),
);

const top = perFolder.flat().sort((a, b) => b.score - a.score).slice(0, 10);

Restringere a un solo documento

Utile per «trova questa clausola in questo contratto» invece che in tutta la cartella.

JSON
{
  "query": "liability cap",
  "limit": 3,
  "documentIds": ["7a2e5c9b-1f40-4d83-b6a1-3c9e0d7f2b58"]
}
Ricerca | IntelligenceBox