Collections

Learn how to create and manage Collections to organize your documents for persistent search and RAG chat.

Documents must be organized, parsed, and indexed before they can be searched or used in conversation. A Collection is the fundamental logical container for documents within a Workspace. Every document you upload for persistent search and chat must belong to exactly one collection.

📦 The Collection Concept

A Collection is a logical container for documents within a Workspace. Every document you upload for persistent search and chat must belong to exactly one collection. Collections act as the primary scope for the RAG engine.

 ┌────────────────────────────────────────────────────────────────────┐
 │                            Workspace                               │
 │                                                                    │
 │     ┌────────────┐                         ┌─────────────┐         │
 │     │ SEARCH API │ ──────┐         ┌────── │ CHAT SESSION│         │
 │     └────────────┘       │         │       └─────────────┘         │
 │                          ▼         ▼                               │
 │       ┌────────────────────────────────────────────────────┐       │
 │       │               Target Collection(s)                 │       │
 │       │  ┌────────────────────────┐  ┌───────────────────┐ │       │
 │       │  │ Collection "Marketing" │  │ Collection "Legal"│ │       │
 │       │  │ ┌──────┐ ┌──────┐      │  │ ┌──────┐          │ │       │
 │       │  │ │ Doc1 │ │ Doc2 │      │  │ │ Doc3 │          │ │       │
 │       │  │ └──────┘ └──────┘      │  │ └──────┘          │ │       │
 │       │  └────────────────────────┘  └───────────────────┘ │       │
 │       └────────────────────────────────────────────────────┘       │
 └────────────────────────────────────────────────────────────────────┘

Collections define the indexing and processing rules for all documents they contain. Each collection binds:

Parser Blueprint — The specific OCR/layout engine used to extract text from files uploaded to this collection.
Embedder Blueprint — The specific vector model used to convert the extracted text chunks into mathematical embeddings.
Vector Configuration — The dense vector size, distance metric (Cosine, Dot, Euclidean), and sparse vector names (e.g., bm25). This defines the underlying Qdrant schema.
Pipeline Config — Collection-specific overrides for search thresholds and generation limits.

Collections act as the primary scope for search and chat queries. When you ask a question, you specify which Collection(s) the AI should draw context from.

Permanent Index Schema

The underlying vector index (dense size, distance metric, and sparse names) is immutable once created. To change these settings or switch to a model with different dimensions, a new Collection must be created.

Warning on Blueprint Swapping

While you can update the embedderId of a collection, the new model must produce vectors of the same dimension as the original. If dimensions do not match, all subsequent ingestion and search operations will fail.

🛠️ Collection Management

Collections support standard lifecycle operations to organize your documents. For a detailed technical reference of every field and parameter, see the API Collection Reference.

Create a Collection

The simplest way to create a collection is to link an existing embedder configuration. The system will automatically infer the correct vector size based on the model.

curl -X POST "https://api.axelered.com/v1/w/{workspace_id}/col" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer Docs",
    "embedderId": "0190a1b2-c3d4-5e6f-7890-123456789abc"
  }'

Read, List & Update

To manage your existing collections and their processing rules, use the following specialized endpoints:

List Collections: Retrieve all collections within a specific workspace.
Read Collection: Fetch the complete metadata, vector configuration, and pipeline settings for a collection.
Update Collection: Safely update names or modify pipeline configs via shallow merging.

Delete a Collection

Collections use soft-deletion. When deleted, the collection is hidden from queries, but its documents remain in storage for audit trails.

curl -X DELETE "https://api.axelered.com/v1/w/{workspace_id}/col/{collection_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

🚀 Next Steps

Once your collection is created, it's ready to accept data.

Learn how to upload documents directly in the Document Uploads guide.
Automate continuous ingestion from external sources with Connectors.