IntelligenceBox

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": "8f2c1d40-33ab-4e7e-9c15-6a0b2e91d774",
    "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 è quello in cui la richiesta legge davvero: l’azienda indicata dagli header di organizzazione, se il proprietario della chiave ne è membro, altrimenti il suo workspace personale, che ha per id quello dell’utente. Se ti aspettavi un’organizzazione e vedi PERSONAL, l’header non è arrivato oppure la chiave è di qualcuno che non ne è membro: una scrittura in quell’organizzazione risponderebbe 403.

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.

Discovery | IntelligenceBox