LightRAG/specs/001-multi-workspace-server/contracts/workspace-routing.md

API Contract: Workspace Routing

Date: 2025-12-01 Feature: 001-multi-workspace-server

Overview

This feature adds workspace routing via HTTP headers. No new API endpoints are introduced; existing endpoints are enhanced to support multi-workspace operation through header-based routing.

Contract Changes

New Request Headers

All existing API endpoints now accept these optional headers:

Header	Type	Required	Description
LIGHTRAG-WORKSPACE	string	No*	Primary workspace identifier
X-Workspace-ID	string	No*	Fallback workspace identifier

* Required when LIGHTRAG_ALLOW_DEFAULT_WORKSPACE=false

Header Priority:

1. LIGHTRAG-WORKSPACE (if present and non-empty)
2. X-Workspace-ID (if present and non-empty)
3. Default workspace from config (if headers missing)

Workspace Identifier Format

Valid workspace identifiers must match:

• Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$
• Length: 1-64 characters
• First character: alphanumeric
• Subsequent characters: alphanumeric, hyphen, underscore

Valid Examples:

• tenant-123
• my_workspace
• ProjectAlpha
• user42_prod

Invalid Examples:

• _hidden (starts with underscore)
• -invalid (starts with hyphen)
• a repeated 100 times (too long)
• path/traversal (contains slash)

Error Responses

New error responses for workspace-related issues:

400 Bad Request - Missing Workspace Header

Condition: No workspace header provided and LIGHTRAG_ALLOW_DEFAULT_WORKSPACE=false

{
  "detail": "Missing LIGHTRAG-WORKSPACE header. Workspace identification is required."
}

400 Bad Request - Invalid Workspace Identifier

Condition: Workspace identifier fails validation

{
  "detail": "Invalid workspace identifier 'bad/id': must be 1-64 alphanumeric characters (hyphens and underscores allowed, must start with alphanumeric)"
}

503 Service Unavailable - Workspace Initialization Failed

Condition: Failed to initialize workspace instance (storage unavailable, etc.)

{
  "detail": "Failed to initialize workspace 'tenant-123': Storage connection failed"
}

Affected Endpoints

All existing endpoints are affected. The workspace header determines which LightRAG instance processes the request.

Document Endpoints

• POST /documents/scan
• POST /documents/upload
• POST /documents/text
• POST /documents/batch
• DELETE /documents/{doc_id}
• GET /documents
• GET /documents/{doc_id}

Query Endpoints

• POST /query
• POST /query/stream

Graph Endpoints

• GET /graph/label/list
• POST /graph/label/entities
• GET /graphs

Ollama-Compatible Endpoints

• POST /api/chat
• POST /api/generate
• GET /api/tags

Unaffected Endpoints

These endpoints operate at server level (not workspace-scoped):

• GET /health
• GET /auth-status
• POST /login
• GET /docs

Example Usage

Single-Workspace Mode (Backward Compatible)

No changes required. Requests without workspace headers use the default workspace.

# Uses default workspace (from WORKSPACE env var)
curl -X POST http://localhost:9621/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "What is LightRAG?"}'

Multi-Workspace Mode

Include workspace header to target specific workspace:

# Target tenant-a workspace
curl -X POST http://localhost:9621/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LIGHTRAG-WORKSPACE: tenant-a" \
  -d '{"query": "What is in this workspace?"}'

# Target tenant-b workspace
curl -X POST http://localhost:9621/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LIGHTRAG-WORKSPACE: tenant-b" \
  -d '{"query": "What is in this workspace?"}'

Strict Multi-Tenant Mode

When LIGHTRAG_ALLOW_DEFAULT_WORKSPACE=false:

# This will return 400 error
curl -X POST http://localhost:9621/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "Missing workspace header"}'

# Response:
# {"detail": "Missing LIGHTRAG-WORKSPACE header. Workspace identification is required."}

Response Headers

No new response headers are added. The workspace used for processing is logged server-side but not returned to the client (to avoid information leakage in error cases).

Backward Compatibility

Scenario	Behavior
Existing client, no workspace header	Uses default workspace (unchanged behavior)
Existing config, new server version	Works unchanged (default workspace = WORKSPACE env var)
New config vars not set	Falls back to existing WORKSPACE env var