API reference

Discovery

Four read-only endpoints that let a client work out what it is talking to instead of hardcoding assumptions: whose key this is, which models actually have credentials, which tools exist, and what the API surface looks like on this particular box.

Who am I?#

GET/api/public/meAPI key

The identity behind the credential, the workspace the request resolved to, and a few counts.

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

The cheapest health check that means something

/health tells you the box is up. /api/public/me tells you the box is up and your key still works and which workspace you landed in. Use it at startup so a revoked key fails immediately instead of on the first real call.

workspace reflects the organization headers you sent. If you expected an organization and see PERSONAL, the header did not arrive.

Available models#

GET/api/public/modelsAPI key

The local model plus every cloud model the box knows, each flagged with whether a credential is actually configured.

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 is the field that matters

A model appearing in cloud only means the box knows about it. If hasCredential is false, nobody has entered an API key for that provider and requests using it will fail. Filter on it before offering a model choice to your users.

Omit the provider and model from a chat request and the box uses its local model — which always works, costs nothing per token and never leaves the machine.

Available tools#

GET/api/public/toolsAPI key

The built-in tool catalog. These keys are what you put in builtInTools when creating an assistant.

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 means the tool needs an external account linked in the desktop app before it does anything. See assistants → tools.

The capability map#

GET/api/public/capabilitiesAPI key

Every public endpoint on this box, grouped by capability, as 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" }
      ]
    }
  ]
}

Built for agents

This endpoint exists so an LLM agent given nothing but a box URL and a key can find out what it is allowed to do, without being handed a hardcoded tool list. It is also the honest answer to “does my box support this yet?” — endpoints ship with the firmware, so an older box reports a shorter map.

The human-readable version of the same map is Capabilities.