Caricare file

Endpoint

POST /api/public/vectors/:id/files

L’:id è l’ID della cartella (vector). Lo trovi in Cartelle. La richiesta deve essere multipart/form-data con il file in un campo chiamato file.

Caricare un file

curl -X POST BOX_URL/api/public/vectors/550e8400-e29b-41d4-a716-446655440000/files \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf"

Richiesta

Invia un file per richiesta, come multipart/form-data.

Risposta

Un caricamento riuscito restituisce 202 Accepted: il file è salvato e messo in coda per l’acquisizione (l’indicizzazione avviene in background, non è finita quando la richiesta ritorna).

{
  "status": "ok",
  "message": "File queued for ingestion pipeline",
  "collection": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    {
      "filename": "report.pdf",
      "originalFilename": "report.pdf",
      "client_id": "report-2026-q4",
      "path": "/data/dataai/550e8400-.../report.pdf",
      "size": 248173,
      "mimetype": "application/pdf",
      "relativePath": "550e8400-e29b-41d4-a716-446655440000/report.pdf"
    }
  ],
  "task_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

Caricare in una sottocartella

Passa relativePath per mettere il file in una sottocartella annidata. L’ultimo segmento viene trattato come nome del file e le cartelle mancanti vengono create automaticamente.

curl -X POST BOX_URL/api/public/vectors/550e8400-e29b-41d4-a716-446655440000/files \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./q4-results.pdf" \
  -F "relativePath=reports/2026/q4.pdf"

Tipi di file supportati

La maggior parte delle cartelle usa la pipeline di acquisizione completa, che accetta una gamma ampia di formati:

• Documenti: pdf, doc, docx, rtf, odt, ppt, pptx
• Fogli di calcolo: xlsx, xls, ods, csv
• Testo e markup: txt, md, markdown, html, json, xml
• Email: msg, p7m
• Immagini (OCR): png, jpg, jpeg, gif, webp, bmp, tiff
• Codice sorgente e configurazione: i linguaggi e i formati di configurazione più comuni (py, js, ts, java, go, rs, sql, yaml, toml e altri)

La dimensione massima è 1 GiB per file. I file troppo grandi e i tipi non supportati vengono rifiutati con 422. Alcune cartelle sono configurate con una pipeline leggera che accetta solo PDF e immagini: in quel caso gli altri formati vengono rifiutati.

Elencare i file di una cartella

Elenca i file di una cartella e il loro stato di acquisizione. Usalo per confermare che un caricamento ha finito di indicizzare (status: "completed").

GET /api/public/vectors/:id/files

Parametri di query

Risposta

{
  "collection": "550e8400-e29b-41d4-a716-446655440000",
  "total": 12,
  "limit": 100,
  "offset": 0,
  "files": [
    {
      "id": "f1e2d3c4-...",
      "name": "report.pdf",
      "folder": "reports/2026",
      "relativePath": "550e8400-.../reports/2026/report.pdf",
      "size": 248173,
      "status": "completed",
      "phase": "done",
      "progress": 100,
      "error": null,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:35:00Z"
    }
  ]
}

Leggere, scaricare, sostituire ed eliminare un file

Tutte queste operazioni riguardano un singolo file, identificato dal suo fileId (che trovi nell’elenco qui sopra).

Leggere i metadati di un file

GET /api/public/vectors/:id/files/:fileId

Restituisce { "file": { ... } } con gli stessi campi di una voce dell’elenco.

Scaricare il contenuto di un file

curl BOX_URL/api/public/vectors/:id/files/:fileId/content \
  -H "x-api-key: YOUR_API_KEY" \
  -o report.pdf

Trasmette i byte grezzi con un nome file in Content-Disposition. I file archiviati solo nel cloud non si possono scaricare e restituiscono 415.

Sostituire un file

Carica una nuova versione al posto della precedente: il vecchio file (e i suoi dati di indice) viene rimosso e il sostituto viene riacquisito nella stessa sottocartella. Restituisce 202 Accepted, come un caricamento.

curl -X PUT BOX_URL/api/public/vectors/:id/files/:fileId \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report-v2.pdf"

Eliminare un file

curl -X DELETE BOX_URL/api/public/vectors/:id/files/:fileId \
  -H "x-api-key: YOUR_API_KEY"

Risposta:

{
  "status": "ok",
  "deleted": true,
  "file_id": "f1e2d3c4-...",
  "errors": []
}

Errori