List Folders

Get all document folders (vectors) available to you. You need folder IDs to use RAG (search your documents). Folders are the foundation of IntelligenceBox's retrieval-augmented generation pipeline. Each folder contains indexed documents that the AI can search through when answering questions, making your responses grounded in your actual data rather than general knowledge alone.

Endpoint

GET /api/public/vectors

Request

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

Response

{
  "vectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Company Documents",
      "description": "Internal policies and procedures",
      "folder": "/path/to/folder",
      "iconName": "Folder",
      "accentColor": "#E0F2FE",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Research Papers",
      "description": "Academic papers collection",
      "folder": "/path/to/research",
      "createdAt": "2024-01-20T14:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Use this in chat requests as `vector` parameter
`name`	string	Folder display name
`description`	string	Folder description
`folder`	string	File system path
`createdAt`	string	Creation timestamp

Get Folder by ID

Get details for a specific folder.

GET /api/public/vectors/:id

Request

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

Response

{
  "vector": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Company Documents",
    "description": "Internal policies and procedures",
    "folder": "/path/to/folder",
    "topK": 5,
    "filter": 0,
    "strategy": "CHUNK"
  }
}

Use in Chat

Once you have a folder 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": "What do my documents say about X?"}],
    "boxAddress": "BOX_URL",
    "vector": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

You can search multiple folders at once:

"vector": ["folder-id-1", "folder-id-2", "folder-id-3"]

Best Practices

Organize by topic: Keep folders focused on a single subject area such as "HR Policies" or "Product Specs". This improves retrieval accuracy because the AI searches a more relevant corpus.
Cache folder IDs: Folder IDs are stable and do not change. Fetch the list once and cache it in your application rather than calling this endpoint before every chat request.
Use descriptions: The description field helps you programmatically select the right folder. For example, you could match user intent to folder descriptions before passing the ID to the chat endpoint.
Combine strategically: When passing multiple folder IDs to the chat endpoint, the AI searches across all of them. Combine folders that are complementary, but avoid adding unrelated folders as that can dilute result relevance.

Related Endpoints

Chat -- Pass folder IDs via the vector parameter to enable RAG
List Assistants -- Assistants can have folders pre-attached, so you may not need to specify them manually