API reference

Assistants

An assistant packages a system prompt, the folders it may search and the tools it may call into something reusable. One created through the API is indistinguishable from one built in the app: it appears in the assistant list, can be used in chat, and can be edited by its owner in the UI.

List assistants#

GET/api/public/assistantsAPI key

Every assistant the key owner can use — their own, plus any shared with the team.

Query

limitinteger: How many to return, 1–200.Default: 50.
offsetinteger: Rows to skip, for paging.Default: 0.
searchstring: Case-insensitive filter on the assistant name.

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

Instructions are truncated in the list

The list returns the first 200 characters of instructions so a long prompt does not dominate the payload. Fetch a single assistant to get the full text.

Create an assistant#

POST/api/public/assistantsAPI key

Creates the assistant and makes the caller its owner.

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

Request body

Field

namestringrequired: Display name. Max 120 characters.
instructionsstring: The system prompt — this is what actually defines the assistant's behaviour. Be specific about scope, tone and what to do when the answer is not in the documents.
descriptionstring: One line describing the assistant. Shown in the assistant list.
handlestring: The @mention name: lowercase letters and digits only, unique across the box. Derived from name when omitted.
visibility"PRIVATE" | "TEAM" | "PUBLIC": PRIVATE is visible only to the creator; TEAM shares it with the workspace. Sharing grants use, never edit.Default: "PRIVATE".
vectorIdsstring[]: Folders this assistant may search. IDs come from the folders endpoint. Max 50.
builtInToolsobject: A { toolKey: boolean } map — see tools. Keys you leave out are off.
permissionMode"auto" | "ask" | "bypass": How tool calls are gated. auto runs reads on its own but pauses before anything with an external side effect; ask confirms every tool; bypass never prompts.Default: "auto".
iconstring: Lucide icon name used as the avatar, e.g. Scale, Stethoscope, Wrench.
colorstring: Hex tint behind the icon, e.g. #3B82F6.
customImagestring: Image URL used instead of the icon.
suggestionsarray: Starter prompts shown on the assistant's empty chat screen. Each entry is { label, prompt }. Max 12.
enabledboolean: Set false to create it switched off.Default: true.

201Assistant created.
403One or more vectorIds are folders the key owner cannot access. The offending ids are listed in details.
409The requested handle is already taken.

Folders are validated, not silently dropped

Attaching a folder the caller cannot read would quietly widen access to it. Instead the whole request is rejected with a 403 naming the folders at fault — so a typo in an id fails loudly rather than producing an assistant with a missing source.

Tools#

What the assistant is allowed to do beyond reading its folders. Ask the box for the live list with GET /api/public/tools.

Core tools

Key	What it does
`calculate`	Arithmetic and unit conversions.
`webSearch`	Search the public web and read the results.
`fetch`	Download and read a specific web page.
`getWeather`	Current conditions and forecast.
`addAReasoningStep`	Let the model plan out loud before answering.
`memory`	Remember facts across conversations.
`assistant`	Delegate a sub-task to another assistant.
`createWidget`	Build interactive widgets inside the answer.
`plot`	Render charts from data.
`codeInterpreter`	Run Python in a sandbox (standard library only).

Integrations

Keys prefixed int_ connect the assistant to an external account: 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.

Enabling a flag does not connect an account

Integrations need the account linked in the desktop app first. Turning the flag on for an unconnected service is accepted, but the tool will not work until someone completes the connection in Settings → Integrations.

Get an assistant#

GET/api/public/assistants/:idAPI key

The full assistant, including the complete instructions and the folders it can search.

Update an assistant#

PATCH/api/public/assistants/:idAPI key

Owner only. Fields you leave out are untouched.

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-…"]
  }'

Collections replace, they do not merge

vectorIds, builtInTools and suggestions overwrite the previous value wholesale. To add one folder, send the full list including the ones already attached.

200Updated.
404No such assistant, or the key owner is not its owner. A TEAM assistant you can use but not edit answers 404 rather than confirming it exists.

Delete an assistant#

DELETE/api/public/assistants/:idAPI key

Owner only. Conversations that used the assistant are kept.

JSON

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

Using the assistant#

Pass its id to the chat endpoint and it brings its prompt, folders and tools with it.

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

See the chat reference for the full request shape and parsing the stream for reading the answer.