Cartelle | IntelligenceBox

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

Chi apre una cartella#

Vale la regola dell’app. Il proprietario della chiave apre una cartella — i dettagli, i file, la ricerca — se gli è stata condivisa, se è sua, oppure se è condivisa con un’azienda di cui fa parte. La cartella privata di un collega resta chiusa agli altri membri dell’azienda, amministratori compresi. Una cartella creata dentro un’azienda resta del suo proprietario finché ne fa parte: se esce dall’azienda la perde, sia in lettura sia in scrittura. Per modificarla serve in più esserne proprietario o editor.

Una cartella che la chiave non apre risponde 404 ai dettagli e alla ricerca, 403 ai file e alle modifiche.

Elencare le cartelle#

GET/api/public/vectorsAPI key

Le cartelle che il proprietario della chiave ha creato o che gli sono state condivise, finché le può aprire, dalla più recente. Una cartella condivisa con tutta l’azienda si apre con il suo id anche se qui non compare.

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 nel workspace della richiesta, 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.
403La richiesta indica un workspace di cui il proprietario della chiave non è membro: non viene creata nessuna cartella.

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. Serve essere proprietario o editor della cartella, altrimenti la risposta è 403.

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. Può farlo solo il proprietario della cartella: a chiunque altro, editor compresi, risponde 403.

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.