Chapter 2: Workspaces - Organizing Your Knowledge

March 2, 2026 · View on GitHub

Welcome to Chapter 2: Workspaces - Organizing Your Knowledge. In this part of AnythingLLM Tutorial: Self-Hosted RAG and Agents Platform, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

Create and manage workspaces to organize documents, conversations, and knowledge domains.

Overview

Workspaces are the fundamental organizational unit in AnythingLLM. They allow you to create isolated knowledge bases for different projects, teams, or topics, each with their own documents, chat history, and configuration.

Workspace Concepts

What is a Workspace?

A workspace represents a self-contained knowledge domain containing:

Documents: Your source materials
Chat History: Conversation threads
Configuration: Custom settings
Embeddings: Vector representations
Access Control: User permissions

Use Cases for Workspaces

# Project-based organization
Workspaces:
  - "Product Documentation"    # User guides, API docs
  - "Engineering Handbook"     # Internal processes, standards
  - "Research Papers"         # Academic articles, studies
  - "Customer Support"        # FAQ, troubleshooting guides
  - "Legal Documents"         # Contracts, policies, compliance

# Team-based organization
Workspaces:
  - "Frontend Team"           # React docs, UI guidelines
  - "Backend Team"           # API specs, database schemas
  - "DevOps Team"            # Infrastructure docs, runbooks
  - "Product Team"           # Requirements, user research

# Domain-based organization
Workspaces:
  - "Machine Learning"        # ML papers, tutorials
  - "Security"               # Security policies, threat models
  - "Compliance"             # Regulatory documents, audits

Creating Workspaces

Basic Workspace Creation

# Via Web Interface
1. Click "New Workspace" in the sidebar
2. Enter workspace name
3. Add description (optional)
4. Choose privacy settings
5. Create workspace

Advanced Workspace Configuration

{
  "name": "Advanced Workspace",
  "description": "Workspace with custom configuration",
  "settings": {
    "chat_mode": "chat",
    "embedding_model": "text-embedding-3-small",
    "similarity_threshold": 0.25,
    "max_tokens": 2048,
    "temperature": 0.7,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  },
  "permissions": {
    "public": false,
    "users": ["user1@example.com", "user2@example.com"],
    "groups": ["engineering", "product"]
  }
}

Workspace Templates

# Create workspace from template
curl -X POST http://localhost:3001/api/v1/workspace \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Documentation",
    "template": "technical_docs",
    "documents": [
      {"url": "https://api.example.com/docs"},
      {"file": "api-reference.pdf"}
    ]
  }'

Workspace Management

Listing Workspaces

# Via API
curl http://localhost:3001/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "workspaces": [
    {
      "id": "ws-123",
      "name": "Product Documentation",
      "description": "User guides and API docs",
      "createdAt": "2024-01-01T00:00:00Z",
      "lastUpdated": "2024-01-02T00:00:00Z",
      "documentCount": 15,
      "messageCount": 234
    }
  ]
}

Updating Workspace Settings

# Update workspace configuration
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Documentation",
    "description": "Latest user guides and API documentation",
    "settings": {
      "chat_mode": "query",
      "temperature": 0.3
    }
  }'

Workspace Deletion

# Delete workspace (irreversible!)
curl -X DELETE http://localhost:3001/api/v1/workspace/ws-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Or via web interface with confirmation

Document Organization

Adding Documents to Workspaces

# Upload single file
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@user-guide.pdf"

# Upload multiple files
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@guide1.pdf" \
  -F "files=@guide2.pdf"

# Add from URL
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com/api-reference",
    "title": "API Reference"
  }'

Document Management

# List documents in workspace
curl http://localhost:3001/api/v1/workspace/ws-123/documents \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get document details
curl http://localhost:3001/api/v1/workspace/ws-123/document/doc-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete document
curl -X DELETE http://localhost:3001/api/v1/workspace/ws-123/document/doc-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Document Folders and Organization

# Create folder structure
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/folder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Documentation",
    "parentId": null
  }'

# Upload to specific folder
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@api-guide.pdf" \
  -F "folderId=folder-123"

Chat Management

Chat Sessions

# Start new chat session
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the main features?",
    "sessionId": "chat-001"
  }'

# Continue existing chat
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you elaborate on the API authentication?",
    "sessionId": "chat-001"
  }'

Chat History

# Get chat history
curl http://localhost:3001/api/v1/workspace/ws-123/chats \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get specific chat thread
curl http://localhost:3001/api/v1/workspace/ws-123/chat/chat-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete chat history
curl -X DELETE http://localhost:3001/api/v1/workspace/ws-123/chat/chat-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Chat Settings

# Configure chat behavior per workspace
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat": {
      "mode": "chat",  // "chat" or "query"
      "model": "gpt-4o",
      "temperature": 0.7,
      "maxTokens": 2048,
      "systemPrompt": "You are a helpful assistant that answers questions about our product documentation."
    }
  }'

Access Control

User Permissions

# Add user to workspace
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "role": "editor"  // "viewer", "editor", "admin"
  }'

# Update user permissions
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123/users/user-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

# Remove user from workspace
curl -X DELETE http://localhost:3001/api/v1/workspace/ws-123/users/user-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Public Workspaces

# Make workspace public (read-only)
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123/visibility \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "public": true,
    "publicReadOnly": true
  }'

# Access public workspace without authentication
curl http://localhost:3001/api/v1/public/workspace/ws-123/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is this workspace about?"}'

Workspace Analytics

Usage Statistics

# Get workspace analytics
curl http://localhost:3001/api/v1/workspace/ws-123/analytics \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "documentCount": 25,
  "totalTokens": 150000,
  "chatCount": 150,
  "messageCount": 450,
  "topQueries": [
    {"query": "how to authenticate", "count": 12},
    {"query": "api limits", "count": 8},
    {"query": "troubleshooting", "count": 6}
  ],
  "usageByDay": [
    {"date": "2024-01-01", "queries": 25, "documents": 2},
    {"date": "2024-01-02", "queries": 30, "documents": 0}
  ]
}

Performance Metrics

# Get performance data
curl http://localhost:3001/api/v1/workspace/ws-123/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "averageResponseTime": 2.3,
  "querySuccessRate": 0.98,
  "documentProcessingTime": 45.2,
  "vectorSearchTime": 0.15,
  "llmResponseTime": 2.1
}

Workspace Templates

Creating Templates

# Save workspace as template
curl -X POST http://localhost:3001/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Documentation Template",
    "description": "Standard template for API documentation workspaces",
    "workspaceId": "ws-123"
  }'

# List available templates
curl http://localhost:3001/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create workspace from template
curl -X POST http://localhost:3001/api/v1/workspace/from-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "template-456",
    "name": "My API Docs",
    "description": "Project-specific API documentation"
  }'

Standard Templates

# Predefined templates
templates:
  - name: "Software Documentation"
    description: "For software projects and technical documentation"
    folders: ["Guides", "API Reference", "Tutorials", "Troubleshooting"]
    settings:
      chat_mode: "query"
      temperature: 0.3

  - name: "Research Papers"
    description: "For academic and research document collections"
    folders: ["Papers", "Notes", "References", "Summaries"]
    settings:
      chat_mode: "chat"
      temperature: 0.7
      max_tokens: 4096

  - name: "Customer Support"
    description: "For support documentation and FAQs"
    folders: ["FAQ", "Troubleshooting", "How-to Guides", "Contact Info"]
    settings:
      chat_mode: "chat"
      temperature: 0.8

Workspace Migration

Exporting Workspaces

# Export workspace configuration
curl -X GET http://localhost:3001/api/v1/workspace/ws-123/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output workspace-config.json

# Export with documents (large files)
curl -X GET "http://localhost:3001/api/v1/workspace/ws-123/export?includeDocuments=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output workspace-backup.tar.gz

Importing Workspaces

# Import workspace configuration
curl -X POST http://localhost:3001/api/v1/workspace/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "config=@workspace-config.json"

# Import complete workspace
curl -X POST http://localhost:3001/api/v1/workspace/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "backup=@workspace-backup.tar.gz"

Advanced Workspace Features

Workspace Hooks

# Webhooks for workspace events
curl -X POST http://localhost:3001/api/v1/workspace/ws-123/hooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["document.added", "chat.created", "workspace.updated"],
    "secret": "webhook-secret"
  }'

Custom Embeddings

# Use custom embedding models
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-embedding-model",
    "dimensions": 768,
    "apiKey": "custom-api-key"
  }'

Workspace Limits

# Set resource limits per workspace
curl -X PUT http://localhost:3001/api/v1/workspace/ws-123/limits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxDocuments": 1000,
    "maxFileSize": "100MB",
    "maxQueriesPerHour": 1000,
    "maxTokensPerQuery": 4096
  }'

Best Practices

Organization Strategies

# Effective workspace organization:

# 1. Purpose-driven workspaces
# - One workspace per major project/component
# - Separate workspaces for different user types
# - Isolated workspaces for sensitive information

# 2. Size considerations
# - Keep workspaces under 1000 documents
# - Balance breadth vs depth of content
# - Consider performance impact of large workspaces

# 3. Access control
# - Use role-based access (viewer/editor/admin)
# - Regular audit of user permissions
# - Consider workspace visibility requirements

Performance Optimization

# Optimize workspace performance:

# 1. Document organization
# - Use folders for logical grouping
# - Remove outdated documents regularly
# - Compress large documents when possible

# 2. Query optimization
# - Use appropriate similarity thresholds
# - Configure chunk sizes for content type
# - Monitor and tune vector search parameters

# 3. Resource management
# - Set appropriate rate limits
# - Monitor usage patterns
# - Scale vector database as needed

Maintenance Tasks

# Regular maintenance:

# 1. Content updates
# - Review and update documents quarterly
# - Archive old chat histories
# - Update embeddings after major content changes

# 2. Performance monitoring
# - Monitor query response times
# - Track document processing times
# - Review usage analytics regularly

# 3. Security audits
# - Audit user access regularly
# - Review workspace permissions
# - Update security settings as needed

Summary

In this chapter, we've covered:

Workspace Creation: Basic and advanced workspace setup
Document Management: Adding, organizing, and managing documents
Chat Management: Sessions, history, and configuration
Access Control: User permissions and public workspaces
Analytics: Usage statistics and performance metrics
Templates: Creating and using workspace templates
Migration: Exporting and importing workspaces
Advanced Features: Hooks, custom embeddings, and limits

Key Takeaways

Organization: Use workspaces to separate knowledge domains
Access Control: Implement appropriate permission levels
Performance: Monitor and optimize workspace performance
Maintenance: Regular content updates and security audits
Templates: Use templates for consistent workspace setup
Analytics: Track usage and performance metrics

Next Steps

Now that you understand workspace organization, let's explore document upload and processing in detail.

Ready for Chapter 3? Document Upload

Generated for Awesome Code Docs

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for workspace, curl, http so behavior stays predictable as complexity grows.

In practical terms, this chapter helps you avoid three common failures:

coupling core logic too tightly to one implementation path
missing the handoff boundaries between setup, execution, and validation
shipping changes without clear rollback or observability strategy

After working through this chapter, you should be able to reason about Chapter 2: Workspaces - Organizing Your Knowledge as an operating subsystem inside AnythingLLM Tutorial: Self-Hosted RAG and Agents Platform, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around localhost, Authorization, Bearer as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

Under the hood, Chapter 2: Workspaces - Organizing Your Knowledge usually follows a repeatable control path:

Context bootstrap: initialize runtime config and prerequisites for workspace.
Input normalization: shape incoming data so curl receives stable contracts.
Core execution: run the main logic branch and propagate intermediate state through http.
Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
Output composition: return canonical result payloads for downstream consumers.
Operational telemetry: emit logs/metrics needed for debugging and performance tuning.

When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.

Source Walkthrough

Use the following upstream sources to verify implementation details while reading this chapter:

AnythingLLM Repository Why it matters: authoritative reference on AnythingLLM Repository (github.com).
AnythingLLM Releases Why it matters: authoritative reference on AnythingLLM Releases (github.com).
AnythingLLM Docs Why it matters: authoritative reference on AnythingLLM Docs (docs.anythingllm.com).
AnythingLLM Website Why it matters: authoritative reference on AnythingLLM Website (anythingllm.com).

Suggested trace strategy:

search upstream code for workspace and curl to map concrete implementation paths
compare docs claims against actual runtime/config code before reusing patterns in production