Riferimento API

Cartelle

Una cartella è un insieme di documenti più le impostazioni che decidono come vengono letti, spezzati in passaggi e trasformati in vettori. Da qui parte tutto ciò che riguarda il recupero: crei una cartella, ci carichi i file e poi la interroghi direttamente oppure la colleghi a un assistente.

Sul filo le cartelle si chiamano vectors

Gli endpoint stanno sotto /api/public/vectors — il nome interno originale di una collezione. L’app desktop chiama lo stesso oggetto «cartella».

Elencare le cartelle#

GET/api/public/vectorsAPI key

Tutte le cartelle a cui il proprietario della chiave ha accesso, dalla più recente.

Query

limitinteger: Quante restituirne, da 1 a 200.Predefinito: 50.
offsetinteger: Righe da saltare, per la paginazione.Predefinito: 0.
searchstring: Filtro sul nome della cartella, senza distinzione tra maiuscole e minuscole.

Shell

curl BOX_URL/api/public/vectors \
  -H "x-api-key: YOUR_API_KEY"

JSON

{
  "vectors": [
    {
      "id": "9c8a2b31-7f45-4d10-8e6a-1b3f0d2c4a58",
      "name": "Contracts 2026",
      "description": "Signed customer agreements",
      "iconName": "FileText",
      "accentColor": "#E0F2FE",
      "strategy": "CHUNK",
      "createdAt": "2026-05-14T08:22:10.114Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false }
}

Gli ID nascono qui

L’id che vedi qui è quello che passi come vectorId nelle richieste di chat, come segmento del percorso quando carichi i file e in vectorIds quando crei un assistente.

Creare una cartella#

POST/api/public/vectorsAPI key

Crea la cartella, predispone la sua collezione vettoriale e la sua cartella di archiviazione. Chi la chiama ne diventa proprietario.

curl -X POST BOX_URL/api/public/vectors \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support tickets",
    "description": "Exported Zendesk tickets, refreshed nightly",
    "strategy": "CHUNK",
    "topK": 8,
    "iconName": "LifeBuoy",
    "accentColor": "#E0F2FE"
  }'

Corpo della richiesta

Campo

namestringobbligatorio: Nome visualizzato. Massimo 200 caratteri.
descriptionstring: Cosa contiene la cartella. Viene mostrato nell’app e usato come contesto quando l’AI decide quale cartella interrogare.
strategy"CHUNK" | "DOCUMENT" | "TABULAR": Come vengono indicizzati i documenti — vedi strategie. Non è modificabile in seguito.Predefinito: "CHUNK".
resume"NONE" | "SHORT" | "MEDIUM" | "FULL": Genera un riassunto per ogni documento al momento dell’acquisizione. I riassunti più lunghi costano più elaborazione ma migliorano il recupero sui documenti lunghi.Predefinito: "NONE".
topKinteger: Quanti passaggi restituisce il recupero, di default, quando questa cartella viene usata in chat. Da 1 a 100.Predefinito: 5.
filternumber: Punteggio minimo di somiglianza, da 0 a 1. Alzalo per guadagnare precisione a scapito della copertura.Predefinito: 0.
iconNamestring: Nome dell’icona Lucide mostrata sulla scheda della cartella.
accentColorstring: Tinta esadecimale della scheda della cartella, ad esempio #E0F2FE.
enableGraphRAGboolean: Costruisce un grafo di conoscenza di entità e relazioni accanto ai vettori. L’acquisizione è più lenta, ma le domande che attraversano più documenti vengono molto meglio.Predefinito: false.
enableTableExtractionboolean: Estrae le tabelle dai PDF trasformandole in strutture interrogabili.Predefinito: false.
enableVisualAnalysisboolean: Trasforma le pagine in immagini e le indicizza. Serve per le scansioni e per gli schemi.Predefinito: false.
enableImageDescriptionboolean: Genera descrizioni testuali delle immagini contenute nei documenti, così diventano ricercabili.Predefinito: false.
pageLimitinteger: Interrompe la lettura di ogni documento dopo questo numero di pagine.

Scegliere una strategia

Strategia	Quando usarla
`CHUNK`	La scelta predefinita. Divide i documenti in passaggi e ne calcola i vettori uno per uno. È la migliore per rispondere a domande su report, contratti, manuali ed email.
`DOCUMENT`	Calcola i vettori sui file interi. Va bene per documenti brevi e autosufficienti, dove un singolo passaggio perderebbe il senso: schede prodotto, curriculum, policy di una pagina.
`TABULAR`	Carica fogli di calcolo e CSV in SQL, così l’AI può aggregare e filtrare invece di tirare a indovinare dal testo. Si interroga dalla chat, non dalla ricerca semantica.

La strategia si fissa alla creazione

Decide dove i dati risiedono fisicamente, quindi cambiarla dopo lascerebbe la cartella a puntare su un’archiviazione mai predisposta. Una PATCH che contiene strategy viene respinta con un 400: crea una cartella nuova.

Risposta

JSON

{
  "vector": {
    "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
    "name": "Support tickets",
    "description": "Exported Zendesk tickets, refreshed nightly",
    "strategy": "CHUNK",
    "topK": 8,
    "embeddingProvider": "qwen",
    "pipelineVersion": "v2",
    "createdAt": "2026-08-03T09:41:07.882Z"
  }
}

201Cartella creata e pronta a ricevere file.

Leggere una cartella#

GET/api/public/vectors/:idAPI key

La cartella con tutte le impostazioni della sua pipeline e il conteggio dei documenti che contiene.

JSON

{
  "vector": {
    "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
    "name": "Support tickets",
    "strategy": "CHUNK",
    "topK": 8,
    "filter": 0,
    "enableGraphRAG": false,
    "embeddingProvider": "qwen",
    "syncEnabled": false,
    "fileCount": 1284
  }
}

Aggiornare una cartella#

PATCH/api/public/vectors/:idAPI key

Cambia i metadati e le impostazioni di recupero. I campi che ometti restano come sono.

Shell

curl -X PATCH BOX_URL/api/public/vectors/3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topK": 12, "filter": 0.35 }'

Le impostazioni di indicizzazione valgono da qui in avanti

Le impostazioni di recupero come topK e filter hanno effetto immediato. Quelle di acquisizione — enableTableExtraction, enableGraphRAG e le altre — valgono solo per i documenti caricati dopo la modifica. Ricarica i file esistenti per applicarle retroattivamente.

Eliminare una cartella#

DELETE/api/public/vectors/:idAPI key

Rimuove la cartella, i suoi documenti, i suoi vettori, il suo grafo di conoscenza e i file archiviati.

Non si torna indietro

Non esiste eliminazione soft e non esiste cestino. Tutto ciò che è indicizzato nella cartella viene distrutto, e ogni assistente che la usava perde semplicemente quella fonte.

JSON

{
  "success": true,
  "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
  "details": {
    "pgvectorDeleted": true,
    "graphDocumentsDeleted": 1284,
    "graphEntitiesDeleted": 8931,
    "imagesDeleted": 402,
    "foldersDeleted": ["/dataai/3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21"]
  },
  "errors": []
}

L’eliminazione tocca più sistemi di archiviazione. errors non è vuoto quando uno di essi fallisce mentre gli altri riescono: la riga della cartella sparisce in ogni caso, quindi tratta quelle voci come pulizie da verificare, non come una chiamata fallita da ripetere.

Passi successivi#

Carica i file nella cartella, così c’è qualcosa da recuperare.
Interrogala direttamente se vuoi i passaggi senza una risposta generata dall’LLM.
Collegala a un assistente così ogni conversazione con quell’assistente potrà usarla.