Riferimento API

Discovery

Quattro endpoint di sola lettura che permettono a un client di capire con cosa sta parlando invece di dare per scontate le cose: di chi è questa chiave, quali modelli hanno davvero le credenziali, quali strumenti esistono e che forma ha l’API su questo box specifico.

Chi sono?#

GET/api/public/meAPI key

L’identità dietro la credenziale, il workspace su cui è finita la richiesta e qualche conteggio.

Shell

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

JSON

{
  "user": {
    "id": "8f2c1d40-33ab-4e7e-9c15-6a0b2e91d774",
    "name": "Giulia Bianchi",
    "email": "giulia@example.com",
    "local": false
  },
  "workspace": {
    "organizationId": null,
    "scope": "PERSONAL"
  },
  "counts": {
    "folders": 12,
    "assistants": 4,
    "unreadNotifications": 3
  }
}

Il controllo di salute più economico che dica qualcosa

/health ti dice che il box è acceso. /api/public/me ti dice che il box è acceso e che la tua chiave funziona ancora e in quale workspace sei finito. Usalo all’avvio, così una chiave revocata fallisce subito invece che alla prima chiamata vera.

workspace riflette gli header di organizzazione che hai inviato. Se ti aspettavi un’organizzazione e vedi PERSONAL, l’header non è arrivato.

Modelli disponibili#

GET/api/public/modelsAPI key

Il modello locale più tutti i modelli cloud che il box conosce, ognuno con l’indicazione se una credenziale è davvero configurata.

JSON

{
  "local": { "available": true, "label": "Local model (default)", "isDefault": true },
  "cloud": [
    {
      "provider": "anthropic",
      "modelKey": "claude-sonnet-4-5",
      "label": "Claude Sonnet 4.5",
      "description": "Fast, strong general reasoning",
      "contextWindow": 200000,
      "maxOutputTokens": 64000,
      "supportsTools": true,
      "supportsVision": true,
      "hasCredential": true
    }
  ]
}

hasCredential è il campo che conta

Che un modello compaia in cloud significa solo che il box lo conosce. Se hasCredential è false, nessuno ha inserito una API key per quel provider e le richieste che lo usano falliranno. Filtra su questo campo prima di proporre una scelta di modello ai tuoi utenti.

Ometti provider e modello da una richiesta di chat e il box usa il suo modello locale — che funziona sempre, non costa nulla a token e non lascia mai la macchina.

Strumenti disponibili#

GET/api/public/toolsAPI key

Il catalogo degli strumenti integrati. Queste chiavi sono quelle che metti in builtInTools quando crei un assistente.

JSON

{
  "tools": [
    {
      "key": "webSearch",
      "group": "core",
      "label": "Web search",
      "description": "Search the public web and read results.",
      "requiresConnection": false
    },
    {
      "key": "int_slack",
      "group": "integration",
      "label": "Slack",
      "description": "Read channels and send messages.",
      "requiresConnection": true
    }
  ]
}

requiresConnection: true significa che lo strumento ha bisogno di un account esterno collegato nell’app desktop prima di poter fare qualcosa. Vedi assistenti → strumenti.

La mappa delle capacità#

GET/api/public/capabilitiesAPI key

Tutti gli endpoint pubblici di questo box, raggruppati per capacità, in JSON.

JSON

{
  "version": 1,
  "authentication": {
    "header": "x-api-key",
    "alternative": "Authorization: Bearer <key>",
    "workspaceHeaders": ["x-organization-id", "x-organization-scope"]
  },
  "capabilities": [
    {
      "group": "Notifications",
      "description": "Push notifications into the IntelligenceBox desktop app.",
      "endpoints": [
        { "method": "POST", "path": "/api/public/notifications", "summary": "Send a notification" },
        { "method": "GET", "path": "/api/public/notifications", "summary": "List notifications" }
      ]
    }
  ]
}

Pensato per gli agenti

Questo endpoint esiste perché un agente LLM a cui vengono dati solo l’URL di un box e una chiave possa scoprire cosa gli è permesso fare, senza ricevere una lista di strumenti scritta a mano. È anche la risposta onesta a «il mio box lo supporta già?»: gli endpoint viaggiano con il firmware, quindi un box più vecchio riporta una mappa più corta.

La versione leggibile della stessa mappa è Cosa puoi fare.