Core Features

Collections

Copy page

Collections help you organize documents into logical groups for easier management, scoped search, and isolated knowledge graphs.

Why Use Collections?

• Organization - Group related documents together
• Scoped Search - Search within specific collections only
• Isolated Graphs - Each collection has its own entity graph
• Access Control - Apply different permissions per collection
• Multi-tenant - Separate knowledge bases for different teams/projects

Collection Structure

Code
 
Cortex
├── Collection: "Research Papers"
│   ├── Document: paper1.pdf
│   ├── Document: paper2.pdf
│   └── Graph: entities & relationships
│
├── Collection: "Product Documentation"
│   ├── Document: user-guide.pdf
│   ├── Document: api-reference.md
│   └── Graph: entities & relationships
│
└── Collection: "default"
    ├── Document: misc1.txt
    └── Graph: entities & relationships

API Usage

Create a Collection

Code
 
curl -X POST "http://localhost:8000/api/collections" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Papers",
    "description": "Academic papers on AI and ML"
  }'

Response:

Code
 
{
  "id": "coll_abc123",
  "name": "Research Papers",
  "description": "Academic papers on AI and ML",
  "document_count": 0,
  "created_at": "2024-01-15T10:30:00Z"
}

List Collections

Code
 
curl "http://localhost:8000/api/collections" \
  -H "X-API-Key: your-api-key"

Code
 
{
  "collections": [
    {
      "id": "coll_abc123",
      "name": "Research Papers",
      "document_count": 45,
      "entity_count": 892
    },
    {
      "id": "default",
      "name": "default",
      "document_count": 12,
      "entity_count": 156
    }
  ]
}

Get Collection Details

Code
 
curl "http://localhost:8000/api/collections/coll_abc123" \
  -H "X-API-Key: your-api-key"

Code
 
{
  "id": "coll_abc123",
  "name": "Research Papers",
  "description": "Academic papers on AI and ML",
  "document_count": 45,
  "chunk_count": 1280,
  "entity_count": 892,
  "relationship_count": 2341,
  "total_size_bytes": 52428800,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

Update a Collection

Rename a collection or update its description. Both fields are optional — only the provided fields are changed.

In the UI: Click the pencil icon on a collection card to rename it inline. Press Enter to save or Escape to cancel.

Via API:

Code
 
curl -X PUT "http://localhost:8000/api/collections/coll_abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Research Papers",
    "description": "Updated description"
  }'

Response:

Code
 
{
  "id": "coll_abc123",
  "name": "AI Research Papers",
  "description": "Updated description",
  "document_count": 45,
  "entity_count": 892
}

Note: The default collection cannot be renamed.

Delete a Collection

Code
 
curl -X DELETE "http://localhost:8000/api/collections/coll_abc123" \
  -H "X-API-Key: your-api-key"

Warning: Deleting a collection also deletes all documents and entities within it.

Document Management

Upload to a Collection

Code
 
# collection_id is a query parameter
curl -X POST "http://localhost:8000/api/upload?collection_id=coll_abc123" \
  -H "X-API-Key: your-api-key" \
  -F "file=@paper.pdf"

Move Documents Between Collections

Code
 
curl -X POST "http://localhost:8000/api/documents/move" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_1", "doc_2"],
    "target_collection_id": "coll_def456"
  }'

List Documents in a Collection

Code
 
curl "http://localhost:8000/api/documents?collection_id=coll_abc123" \
  -H "X-API-Key: your-api-key"

Collection-Scoped Operations

Ask AI and basic search resolve the requested collection against the key's allowed scope; omitting collection_id uses the key's scope. To narrow retrieval to a single permitted collection, pass its collection_id. Basic search scopes its vector, keyword, and metadata legs to that collection's documents. The default Ask AI/context RRF path applies collection clauses to the chunk queries in its vector, keyword, and graph retrieval. The legacy fallback when ENABLE_HYBRID_SEARCH=false also carries scope into its vector and traversal chunk queries. Entity and relationship metadata returned by graph traversal remains global in both paths; chunk scoping does not establish complete graph-context isolation.

Search Within a Collection

Code
 
curl -X POST "http://localhost:8000/api/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "transformer architecture",
    "collection_id": "coll_abc123"
  }'

Ask AI About a Collection

By default, Ask AI searches across all collections. To scope a question to a single collection:

In the UI: Open the Settings panel on the Ask AI page and use the Collection Scope dropdown. It defaults to "All Collections" — select a specific collection to filter. A persistent indicator below the input shows the active scope.

Via API:

Code
 
# Search all collections (default — omit collection_id)
curl -X POST "http://localhost:8000/api/ask" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the common themes across all papers?"
  }'

# Search a specific collection
curl -X POST "http://localhost:8000/api/ask" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the common themes in these papers?",
    "collection_id": "coll_abc123"
  }'

Get Collection Graph

Code
 
curl "http://localhost:8000/api/graph/visualization?collection_id=coll_abc123" \
  -H "X-API-Key: your-api-key"

Default Collection

Documents uploaded without a collection_id go to the default collection.

Configure the default collection name:

Code
 
DEFAULT_COLLECTION=default

Configuration

Code
 
# Enable collections feature
ENABLE_COLLECTIONS=true

# Default collection for uncategorized documents
DEFAULT_COLLECTION=default

Collection-Scoped API Keys

The most powerful use of collections is pairing them with collection-scoped API keys. A key restricted to specific collections can only see and write to those collections — everything else returns a 403. This enables true multi-tenancy from a single Cortex instance.

Create a restricted key

Code
 
curl -X POST http://localhost:8000/api/admin/api-keys \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tenant A - Read Only",
    "permissions": ["read"],
    "collection_scope": "restricted",
    "allowed_collections": ["coll_abc123"]
  }'

Update collection access on an existing key

Code
 
curl -X PATCH http://localhost:8000/api/admin/api-keys/{id} \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_scope": "restricted",
    "allowed_collections": ["coll_abc123", "coll_def456"]
  }'

Enforcement

Endpoint type	Behaviour for restricted key
GET /api/collections	Returns only allowed collections
GET /api/documents	Returns only documents in allowed collections
GET /api/collections/{id}	403 if not in allowed list
GET /api/documents/{id}	403 if document's collection not in allowed list
POST /api/upload?collection_id=...	403 if collection not in allowed list
POST /api/ask with collection_id	403 if collection not in allowed list

New collections are never automatically accessible to existing restricted keys — access must be explicitly granted.

In the UI

Go to Settings → API Key Management → New Key and select Specific Collections to open a multi-select picker. Each restricted key card shows an amber N Collections badge.

Best Practices

1. Meaningful Names - Use descriptive names for easy identification
2. Logical Grouping - Group documents by topic, project, or source
3. Don't Over-Segment - Too many small collections reduce graph connectivity
4. Regular Cleanup - Remove unused collections periodically
5. Use Descriptions - Add descriptions for documentation
6. Pair with scoped keys - For multi-tenant deployments, give each tenant a key restricted to their collection