RAG in a box

RAG in a box is Slab5's managed vector-store surface for developers, apps, MCP clients, and external agents. It lets a workspace create named collections, add custom documents, search by meaning, and review usage without operating a separate vector database.

Collections are workspace-scoped. A collection created in one workspace cannot be queried from another workspace.

RAG in a box uses the same managed Slab5 retrieval layer as Semantic Search and BI Explore, but developer collections are isolated from product indexes. A custom collection cannot return BI metric vectors, workspace search vectors, or another workspace's vectors.

What RAG in a box does

Use RAG in a box when an app or agent needs to retrieve custom knowledge such as:

• product documentation
• customer-specific help content
• implementation notes
• policy snippets
• generated summaries
• app-specific records that are not first-class Slab5 modules

RAG in a box is not a raw file lake. Store the text chunks and metadata you want retrieved. Keep source files in your own application, CMS, object store, or Slab5 records.

Access model

RAG in a box uses workspace credentials and Slab5 app-plane scopes.

Create a workspace API key or MCP client with only the scopes your app needs. A read-only search integration should not receive vector_store:write.

App ownership

RAG collections are always workspace-scoped. They can also be attributed to a registered app when the request uses an app-associated API key.

Use app ownership when a developer-facing app, customer-facing product surface, or agent should have its own retrieval corpus and usage trail. App-owned collections appear in the app detail view and their usage can be filtered by app in Usage and Audit Log.

The app does not replace workspace isolation. The workspace remains the security boundary. The app is the product or integration boundary used for grouping keys, collections, usage, audit events, and optional budget metadata.

Collection lifecycle

1. Create a collection with a stable collection_key.
2. Upsert documents with stable IDs.
3. Search the collection with a natural-language query.
4. Delete documents when source data is removed.
5. Archive the collection when the integration is retired.

Collection dimensions and distance metric are fixed after creation. Create a new collection key if you need to change dimensions.

Use readable, stable collection keys such as product_docs, customer_help, or implementation_notes. Collection keys are developer-facing identifiers. Slab5 still maps them to a tenant/workspace-isolated physical index behind the scenes.

Collection keys should be generated from durable names and kept stable in client code. If you rename a product label in the UI, do not change the collection key unless you are intentionally creating a new collection.

Console workflow

Open RAG in a box in the Slab5 console to manage developer collections without writing code first.

The console supports:

• listing workspace collections
• creating a collection
• adding or updating sample documents
• running retrieval previews
• deleting documents
• archiving collections
• reviewing collection status, dimensions, vector count, and usage

Use the console preview before wiring a collection into an app, workflow, MCP client, or external agent. This helps confirm chunk text, metadata, and retrieval quality before production traffic depends on the collection.

If the collection is created with an app-associated API key, check the app detail page after the operation. The collection should appear under Vector/RAG collections for that app.

REST quickstart

Create a collection:

curl -X POST "$SLAB5_API_BASE_URL/vector-collections" \
  -H "authorization: Bearer $SLAB5_API_KEY" \
  -H "x-slab5-workspace-id: $SLAB5_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{
    "collection_key": "product_docs",
    "name": "Product documentation",
    "description": "Developer-managed semantic collection for product docs.",
    "dimensions": 1536,
    "access_policy": "workspace_scoped"
  }'

Add or update documents:

curl -X POST "$SLAB5_API_BASE_URL/vector-collections/product_docs/documents" \
  -H "authorization: Bearer $SLAB5_API_KEY" \
  -H "x-slab5-workspace-id: $SLAB5_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{
    "documents": [
      {
        "id": "getting-started",
        "source_type": "doc",
        "text": "Slab5 RAG in a box lets developers store, manage, and search workspace-scoped vector collections.",
        "metadata": { "section": "docs", "product_area": "rag" }
      }
    ]
  }'

Search:

curl -X POST "$SLAB5_API_BASE_URL/vector-collections/product_docs/search" \
  -H "authorization: Bearer $SLAB5_API_KEY" \
  -H "x-slab5-workspace-id: $SLAB5_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{
    "query": "How do I add custom data to a workspace vector collection?",
    "top_k": 5,
    "return_metadata": true
  }'

Delete documents:

curl -X DELETE "$SLAB5_API_BASE_URL/vector-collections/product_docs/documents" \
  -H "authorization: Bearer $SLAB5_API_KEY" \
  -H "x-slab5-workspace-id: $SLAB5_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{ "document_ids": ["getting-started"] }'

Archive a collection:

curl -X DELETE "$SLAB5_API_BASE_URL/vector-collections/product_docs" \
  -H "authorization: Bearer $SLAB5_API_KEY" \
  -H "x-slab5-workspace-id: $SLAB5_WORKSPACE_ID"

MCP tools

The same operations are available through MCP when the client has the required Vector Store scopes:

• list_vector_collections
• create_vector_collection
• upsert_vector_documents
• search_vector_collection
• delete_vector_documents
• archive_vector_collection

Use MCP when ChatGPT, Claude, Cursor, or another MCP-compatible agent should retrieve from or manage workspace collections directly.

For production agents, prefer read-only MCP grants unless the agent truly needs to create collections or mutate documents.

Dimensions and models

Supported dimensions:

Use 1536 dimensions when retrieval quality matters most. Use smaller dimensions only when you have tested that recall is acceptable for the collection's use case.

The query embedding dimensions must match the collection dimensions. A 1536-dimension collection must be queried with 1536-dimension embeddings; a 512-dimension collection must be queried with 512-dimension embeddings.

Developer onboarding checklist

1. Create or choose a workspace.
2. Create a Registered App if the integration should have app-level attribution.
3. Create an API key for that app or create a workspace API key.
4. Grant vector_store:read for retrieval; add vector_store:write only for collection management.
5. Create a collection with a stable collection_key.
6. Upsert a small set of representative documents.
7. Run retrieval previews in the console.
8. Verify Usage and Audit Log show the expected app, key, route, request ID, and Vector Store event.
9. Wire the search endpoint or MCP tool into the external app or agent.
10. Monitor collection-level usage from Usage → Intelligence usage.

Troubleshooting

Usage and billing

RAG in a box is metered through workspace usage:

• collection create/archive events
• document upserts and deletes
• embedding input tokens
• vector query events
• vectors returned
• estimated query scan bytes
• estimated bytes returned

Workspace admins can review collection-level usage from Usage → Intelligence usage in the Slab5 console.

The usage drill-down groups operations by collection so admins can see which app, integration, or agent is driving Vector Store usage.