Riferimento API

Assistenti

Un assistente mette insieme un prompt di sistema, le cartelle che può consultare e gli strumenti che può usare, in qualcosa di riutilizzabile. Uno creato tramite API è indistinguibile da uno costruito nell’app: compare nell’elenco degli assistenti, si può usare in chat e il suo proprietario può modificarlo dall’interfaccia.

Elencare gli assistenti#

GET/api/public/assistantsAPI key

Tutti gli assistenti che il proprietario della chiave può usare — i suoi, più quelli condivisi con il team.

Query

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

JSON

{
  "assistants": [
    {
      "id": "1f4b6d20-8c39-4a72-9e05-7d2c8b1a0f63",
      "name": "Contract analyst",
      "handle": "contractanalyst",
      "description": "Answers questions about signed agreements",
      "instructions": "You are a contract analyst. Always cite the clause…",
      "visibility": "TEAM",
      "icon": "Scale",
      "color": "#3B82F6",
      "builtInTools": { "webSearch": false, "calculate": true },
      "vectorIds": ["9c8a2b31-7f45-4d10-8e6a-1b3f0d2c4a58"],
      "vectors": [{ "id": "9c8a2b31-…", "name": "Contracts 2026" }]
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false }
}

Nell’elenco le istruzioni sono troncate

L’elenco restituisce i primi 200 caratteri di instructions, così un prompt lungo non occupa tutta la risposta. Recupera il singolo assistente per avere il testo completo.

Creare un assistente#

POST/api/public/assistantsAPI key

Crea l’assistente e ne rende proprietario chi ha fatto la chiamata.

curl -X POST BOX_URL/api/public/assistants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract analyst",
    "description": "Answers questions about signed agreements",
    "instructions": "You are a contract analyst. Answer only from the documents provided, always cite the clause number, and say plainly when something is not covered.",
    "visibility": "TEAM",
    "icon": "Scale",
    "vectorIds": ["9c8a2b31-7f45-4d10-8e6a-1b3f0d2c4a58"],
    "builtInTools": { "calculate": true, "webSearch": false }
  }'

Corpo della richiesta

Campo

namestringobbligatorio: Nome visualizzato. Massimo 120 caratteri.
instructionsstring: Il prompt di sistema — è questo che definisce davvero il comportamento dell’assistente. Sii preciso su ambito, tono e su cosa fare quando la risposta non è nei documenti.
descriptionstring: Una riga che descrive l’assistente. Compare nell’elenco degli assistenti.
handlestring: Il nome per la @menzione: solo lettere minuscole e cifre, univoco su tutto il box. Se lo ometti viene ricavato da name.
visibility"PRIVATE" | "TEAM" | "PUBLIC": PRIVATE è visibile solo a chi l’ha creato; TEAM lo condivide con il workspace. La condivisione dà il diritto di usarlo, mai di modificarlo.Predefinito: "PRIVATE".
vectorIdsstring[]: Le cartelle che questo assistente può consultare. Gli ID arrivano dall’ endpoint delle cartelle. Massimo 50.
builtInToolsobject: Una mappa { toolKey: boolean } — vedi strumenti. Le chiavi che ometti restano spente.
permissionMode"auto" | "ask" | "bypass": Come vengono filtrate le chiamate agli strumenti. auto esegue da sé le letture ma si ferma prima di qualsiasi effetto esterno; ask chiede conferma per ogni strumento; bypass non chiede mai nulla.Predefinito: "auto".
iconstring: Nome dell’icona Lucide usata come avatar, ad esempio Scale, Stethoscope, Wrench.
colorstring: Tinta esadecimale dietro l’icona, ad esempio #3B82F6.
customImagestring: URL di un’immagine da usare al posto dell’icona.
suggestionsarray: Prompt di avvio mostrati nella schermata di chat vuota dell’assistente. Ogni voce è { label, prompt }. Massimo 12.
enabledboolean: Imposta false per crearlo già disattivato.Predefinito: true.

201Assistente creato.
403Uno o più vectorIds sono cartelle a cui il proprietario della chiave non ha accesso. Gli id incriminati sono elencati in details.
409L’handle richiesto è già occupato.

Le cartelle vengono validate, non scartate in silenzio

Collegare una cartella che chi chiama non può leggere ne allargherebbe l’accesso di nascosto. Per questo l’intera richiesta viene respinta con un 403 che nomina le cartelle colpevoli: un id sbagliato fallisce in modo rumoroso invece di produrre un assistente con una fonte mancante.

Strumenti#

Cosa può fare l’assistente oltre a leggere le sue cartelle. Chiedi al box l’elenco aggiornato con GET /api/public/tools.

Strumenti di base

Chiave	Cosa fa
`calculate`	Aritmetica e conversioni di unità di misura.
`webSearch`	Cerca sul web pubblico e legge i risultati.
`fetch`	Scarica e legge una pagina web specifica.
`getWeather`	Condizioni attuali e previsioni.
`addAReasoningStep`	Permette al modello di ragionare ad alta voce prima di rispondere.
`memory`	Ricorda informazioni da una conversazione all’altra.
`assistant`	Delega un sotto-compito a un altro assistente.
`createWidget`	Costruisce widget interattivi dentro la risposta.
`plot`	Disegna grafici a partire dai dati.
`codeInterpreter`	Esegue Python in una sandbox (solo libreria standard).

Integrazioni

Le chiavi con prefisso int_ collegano l’assistente a un account esterno: int_gmail, int_outlook, int_gcalendar, int_outlook_calendar, int_asana, int_jira, int_slack, int_notion, int_github, int_teams, int_database, int_fattureincloud, int_inbando, int_primis.

Attivare un flag non collega un account

Le integrazioni richiedono che l’account sia prima collegato nell’app desktop. Attivare il flag per un servizio non collegato viene accettato, ma lo strumento non funzionerà finché qualcuno non completa il collegamento in Impostazioni → Integrazioni.

Leggere un assistente#

GET/api/public/assistants/:idAPI key

L’assistente completo, comprese le istruzioni per intero e le cartelle che può consultare.

Aggiornare un assistente#

PATCH/api/public/assistants/:idAPI key

Solo il proprietario. I campi che ometti restano come sono.

Shell

curl -X PATCH BOX_URL/api/public/assistants/1f4b6d20-8c39-4a72-9e05-7d2c8b1a0f63 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a contract analyst. Cite clause numbers. Flag anything unusual.",
    "vectorIds": ["9c8a2b31-…", "3d7e1a04-…"]
  }'

Le collezioni si sostituiscono, non si fondono

vectorIds, builtInTools e suggestions sovrascrivono in blocco il valore precedente. Per aggiungere una cartella, invia l’elenco completo comprese quelle già collegate.

200Aggiornato.
404Nessun assistente con questo id, oppure il proprietario della chiave non ne è il proprietario. Un assistente TEAM che puoi usare ma non modificare risponde 404 invece di confermare che esiste.

Eliminare un assistente#

DELETE/api/public/assistants/:idAPI key

Solo il proprietario. Le conversazioni che hanno usato l’assistente vengono conservate.

JSON

{ "success": true, "id": "1f4b6d20-8c39-4a72-9e05-7d2c8b1a0f63" }

Usare l’assistente#

Passa il suo id all’endpoint di chat e si porta dietro il suo prompt, le sue cartelle e i suoi strumenti.

Shell

curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "contract-review-8821",
    "assistantId": "1f4b6d20-8c39-4a72-9e05-7d2c8b1a0f63",
    "messages": [{ "role": "user", "content": "What is our standard notice period?" }],
    "boxAddress": "BOX_URL"
  }'

Vedi il riferimento della chat per la forma completa della richiesta e leggere la risposta per interpretare lo stream.