Assistenti | IntelligenceBox

Elencare gli assistenti#

GET/api/public/assistantsAPI key

Gli assistenti che il proprietario della chiave può usare nel workspace della richiesta: i suoi, quelli condivisi direttamente con lui e quelli TEAM e PUBLIC di quel workspace.

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 }
}

TEAM e PUBLIC restano nel loro workspace

Gli assistenti del proprietario della chiave, e quelli condivisi direttamente con lui, compaiono sempre. Un assistente TEAM o PUBLIC compare solo nel workspace in cui vive: per elencare quelli di un’azienda invia x-organization-id e x-organization-scope. L’header vale se il proprietario della chiave è membro di quell’azienda; se non lo è, o senza header, la richiesta resta nel suo workspace personale. La chiave di un’app esterna usa il workspace da cui l’app è stata aperta. Gli assistenti di sistema non compaiono.

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.

Nomi delle cartelle

vectorIds elenca tutte le cartelle collegate; vectors riporta id e nome solo di quelle che il proprietario della chiave può aprire nel workspace della richiesta. Un assistente TEAM può avere collegata una cartella privata del suo autore: chi non può aprirla ne vede l’id, non il nome.

Creare un assistente#

POST/api/public/assistantsAPI key

Crea l’assistente nel workspace della richiesta 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.
403La richiesta indica un workspace di cui il proprietario della chiave non è membro (Workspace access denied: non viene creato nulla), oppure uno o più vectorIds sono cartelle a cui 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.

200L’assistente.
404Nessun assistente con questo id, oppure uno che l’elenco non mostrerebbe nel workspace della richiesta: la risposta è la stessa, così non conferma che esista.

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.