List Assistants

Get all AI assistants available to you. Assistants are custom AI personas with specific instructions and attached folders.

Endpoint

GET /api/public/assistants

Request

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

Response

{
  "assistants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Research Helper",
      "handle": "research",
      "description": "Helps analyze research papers",
      "instructions": "You are a helpful research assistant...",
      "icon": "Search",
      "color": "#3B82F6",
      "vectorIds": ["folder-id-1", "folder-id-2"],
      "vectors": [
        { "id": "folder-id-1", "name": "Research Papers" },
        { "id": "folder-id-2", "name": "Notes" }
      ],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Use this in chat requests as `assistantId` parameter
`name`	string	Assistant display name
`handle`	string	Unique handle (URL-friendly)
`description`	string	Short description
`instructions`	string	System prompt (truncated)
`vectorIds`	array	IDs of attached folders
`vectors`	array	Details of attached folders

Get Assistant by ID

Get full details for a specific assistant.

GET /api/public/assistants/:id

Request

curl BOX_URL/api/public/assistants/550e8400-e29b-41d4-a716-446655440001 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "assistant": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Research Helper",
    "handle": "research",
    "description": "Helps analyze research papers",
    "instructions": "You are a helpful research assistant specialized in...",
    "builtInTools": {
      "webSearch": true,
      "calculate": true
    },
    "vectorIds": ["folder-id-1"],
    "vectors": [
      {
        "id": "folder-id-1",
        "name": "Research Papers",
        "description": "Academic papers collection"
      }
    ]
  }
}

Use in Chat

Once you have an assistant ID, use it in the Chat endpoint:

curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-chat",
    "messages": [{"role": "user", "content": "Help me analyze this topic"}],
    "boxAddress": "BOX_URL",
    "assistantId": "550e8400-e29b-41d4-a716-446655440001"
  }'

Note About Folders

Assistants can have folders pre-attached (see vectorIds). When you chat with an assistant:

The assistant's attached folders are automatically searched
You can add more folders with the vector parameter
Both are combined for RAG