List Assistants

Get all AI assistants available to you. Assistants are custom AI personas with specific instructions and attached folders. Use this endpoint to discover which assistants are configured on your IntelligenceBox, inspect their capabilities, and determine which one to use for a given task.

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

Choosing the Right Assistant

When your IntelligenceBox has multiple assistants configured, selecting the right one for each request can significantly improve response quality. Here are some tips:

Match by description: Use the description field to understand what each assistant specializes in. Route user queries to the assistant whose description best matches the topic.
Check attached folders: The vectors array tells you which document collections the assistant has access to. An assistant with relevant folders already attached will produce better RAG-based answers without extra configuration.
Inspect built-in tools: The detailed response from the single-assistant endpoint includes a builtInTools object. If your use case requires web search or calculations, choose an assistant that has those tools enabled.
Use handles for routing: The handle field provides a URL-friendly identifier that is stable and easy to use in configuration files or environment variables.

Related Endpoints

Chat -- Pass the assistant ID via the assistantId parameter
List Folders -- Discover additional folders you can attach to any assistant at chat time