This document describes the REST API endpoints for programmatic interaction with workspaces in AnythingLLM. These endpoints enable developers to create, configure, and manage workspaces, execute chat operations, manage documents, and work with workspace threads via API key authentication.
For information about system-level API endpoints (settings, user management, event logs), see System and Admin API Endpoints. For document upload and management endpoints, see Document API Endpoints. For general API authentication concepts, see API Authentication and Overview.
The workspace API endpoints follow a hierarchical structure based on the workspace slug identifier. All endpoints require API key authentication via the Authorization: Bearer <api_key> header.
Sources: server/endpoints/api/workspace/index.js1-1011 server/endpoints/api/workspaceThread/index.js1-685
These endpoints handle the creation, reading, updating, and deletion of workspace entities. The Workspace model server/models/workspace.js is the primary data structure, and operations are exposed through the apiWorkspaceEndpoints function.
| Endpoint | Method | Purpose | Function Reference |
|---|---|---|---|
/v1/workspace/new | POST | Create new workspace | server/endpoints/api/workspace/index.js22-101 |
/v1/workspaces | GET | List all workspaces with threads | server/endpoints/api/workspace/index.js103-155 |
/v1/workspace/:slug | GET | Get workspace by slug with documents and threads | server/endpoints/api/workspace/index.js157-220 |
/v1/workspace/:slug | DELETE | Delete workspace and all associated data | server/endpoints/api/workspace/index.js222-271 |
/v1/workspace/:slug/update | POST | Update workspace settings | server/endpoints/api/workspace/index.js273-349 |
The workspace creation process at server/endpoints/api/workspace/index.js74-78 calls Workspace.new() and includes telemetry tracking and event logging.
When a workspace is deleted, the following cleanup operations occur:
Sources: server/endpoints/api/workspace/index.js241-265
Workspaces maintain relationships with documents through the workspace_documents table. The API provides endpoints for adding, removing, and pinning documents within a workspace.
| Endpoint | Method | Purpose | Request Body |
|---|---|---|---|
/v1/workspace/:slug/update-embeddings | POST | Add or remove documents | {adds: string[], deletes: string[]} |
/v1/workspace/:slug/update-pin | POST | Pin/unpin a document | {docPath: string, pinStatus: boolean} |
The /update-embeddings endpoint modifies which documents are embedded into a workspace's vector database:
The implementation at server/endpoints/api/workspace/index.js502-522 uses Document.removeDocuments() and Document.addDocuments() to manage vector embeddings.
Pinned documents are always included in the chat context, regardless of similarity search results. The pinning operation:
pinned field via Document.update() server/endpoints/api/workspace/index.js581DocumentManager.pinnedDocs() during chat operationsSources: server/endpoints/api/workspace/index.js448-591
The workspace API provides two chat execution modes: synchronous (blocking) and streaming (Server-Sent Events). Both support chat and query modes, where query mode only uses embedded documents and refuses to answer without relevant context.
| Endpoint | Response Type | Use Case | Handler Class |
|---|---|---|---|
/v1/workspace/:slug/chat | JSON (complete response) | Single-turn interactions, API integrations | ApiChatHandler.chatSync |
/v1/workspace/:slug/stream-chat | SSE (text/event-stream) | Real-time UIs, progressive display | ApiChatHandler.streamChat |
The synchronous chat implementation at server/endpoints/api/workspace/index.js593-721 accepts the following parameters:
message (string): User prompt textmode (string): Either "chat" or "query" from VALID_CHAT_MODE constantsessionId (string, optional): Partition chats by external identifier via api_session_id fieldattachments (array, optional): Image or document attachments with {name, mime, contentString} formatreset (boolean): Clear chat history before executingSources: server/endpoints/api/workspace/index.js593-721 server/utils/chats/apiChatHandler.js112-434
The streaming endpoint returns Server-Sent Events for real-time response display:
Each SSE event contains:
The final event includes close: true and the complete sources array. Implementation at server/endpoints/api/workspace/index.js723-879 uses ApiChatHandler.streamChat() with writeResponseChunk() helper server/utils/helpers/chat/responses.js
The mode validation occurs at server/endpoints/api/workspace/index.js672 and behavior divergence is in ApiChatHandler.chatSync() at server/utils/chats/apiChatHandler.js217-244 and server/utils/chats/apiChatHandler.js345-375
Sources: server/endpoints/api/workspace/index.js723-879 server/utils/chats/apiChatHandler.js451-695
Threads enable multiple conversation contexts within a single workspace. Each thread maintains independent chat history and can be associated with a specific user.
| Endpoint | Method | Purpose | Function |
|---|---|---|---|
/v1/workspace/:slug/thread/new | POST | Create new thread | server/endpoints/api/workspaceThread/index.js21-109 |
/v1/workspace/:slug/thread/:threadSlug/update | POST | Update thread name | server/endpoints/api/workspaceThread/index.js111-190 |
/v1/workspace/:slug/thread/:threadSlug | DELETE | Delete thread and chats | server/endpoints/api/workspaceThread/index.js192-239 |
/v1/workspace/:slug/thread/:threadSlug/chats | GET | Get thread chat history | server/endpoints/api/workspaceThread/index.js241-319 |
/v1/workspace/:slug/thread/:threadSlug/chat | POST | Chat with thread (sync) | server/endpoints/api/workspaceThread/index.js321-461 |
/v1/workspace/:slug/thread/:threadSlug/stream-chat | POST | Chat with thread (stream) | server/endpoints/api/workspaceThread/index.js463-629 |
The thread creation at server/endpoints/api/workspaceThread/index.js87-91 supports optional parameters:
userId (number): Associate thread with user (nullified in single-user mode at line 85)name (string): Custom thread nameslug (string): Custom URL-safe identifierThread chats are isolated from workspace-level chats and other threads through the thread_id field in the workspace_chats table. The chat retrieval query at server/endpoints/api/workspaceThread/index.js302-311 filters by:
Thread chat execution uses the same ApiChatHandler class but passes the thread parameter, which scopes the recentChatHistory lookup and WorkspaceChats.new() save operation.
Sources: server/endpoints/api/workspaceThread/index.js21-629 server/utils/chats/apiChatHandler.js112-434
The API supports multiple conversation partitioning strategies through the api_session_id field and thread system.
The /v1/workspace/:slug/chats endpoint retrieves chat history with optional session filtering:
Query parameters at server/endpoints/api/workspace/index.js413-417:
apiSessionId (string): Filter by session identifierlimit (integer, default 100): Maximum messages to returnorderBy (string, "asc" or "desc"): Sort order by createdAtThe WorkspaceChats.forWorkspaceByApiSessionId() method filters on both workspaceId and api_session_id fields server/endpoints/api/workspace/index.js431-436
Both workspace and thread chat endpoints support a reset parameter that clears history before processing a new message:
This operation sets include: false on all matching chat records, excluding them from future history retrieval. Implementation at server/utils/chats/apiChatHandler.js128-146
Sources: server/endpoints/api/workspace/index.js351-446 server/utils/chats/apiChatHandler.js128-146
The /v1/workspace/:slug/vector-search endpoint exposes the underlying vector search functionality used during chat operations, allowing direct querying of embedded documents.
Request Format:
Response Format:
The implementation at server/endpoints/api/workspace/index.js881-1011 includes parameter parsing:
topN: Defaults to workspace?.topN ?? 4 if invalid server/endpoints/api/workspace/index.js970-974scoreThreshold: Defaults to workspace?.similarityThreshold ?? 0.25 if outside 0-1 range server/endpoints/api/workspace/index.js963-968The search calls VectorDb.performSimilaritySearch() with the same interface used during chat operations, ensuring consistent retrieval behavior.
Sources: server/endpoints/api/workspace/index.js881-1011
Both workspace and thread chat endpoints support attachments with two types: images and documents. Document attachments use a special MIME type for processing.
The document attachment processing at server/utils/chats/apiChatHandler.js39-96 follows this flow:
application/anythingllm-document vs others)contentString and write to hotdir server/utils/chats/apiChatHandler.js70-81Collector.parseDocument() to extract text server/utils/chats/apiChatHandler.js83-84contextTexts array server/utils/chats/apiChatHandler.js283-293Image attachments are passed directly to the LLM without processing for vision-capable models.
Request Example:
Sources: server/utils/chats/apiChatHandler.js39-96 server/utils/chats/apiChatHandler.js280-293
The workspace update endpoint accepts a comprehensive set of configuration fields that control LLM behavior, RAG parameters, and agent settings.
| Field | Type | Purpose | Default |
|---|---|---|---|
name | string | Workspace display name | Required on creation |
slug | string | URL-safe identifier | Auto-generated from name |
chatProvider | string | Override system LLM provider | Inherits from process.env.LLM_PROVIDER |
chatModel | string | Model for chat completions | Provider-specific default |
openAiTemp | float | Temperature (0-1) | Provider default |
openAiHistory | integer | Message history limit | 20 |
openAiPrompt | string | Custom system prompt | Default prompt template |
queryRefusalResponse | string | Response when no context found | "There is no relevant information..." |
chatMode | string | "chat" or "query" | "chat" |
topN | integer | Max context chunks | 4 |
similarityThreshold | float | Minimum similarity score (0-1) | 0.25 |
agentProvider | string | Agent LLM provider | Inherits from chatProvider |
agentModel | string | Model for agent operations | Inherits from chatModel |
vectorSearchMode | string | "normal" or "rerank" | "normal" |
The update operation at server/endpoints/api/workspace/index.js339-343 calls Workspace.update() which validates and persists these fields to the workspaces table.
Workspace-level LLM configuration overrides system defaults:
This allows different workspaces to use different LLM providers (e.g., OpenAI for one workspace, Anthropic for another) within the same AnythingLLM instance. Implementation at server/endpoints/api/workspace/index.js699-700
Sources: server/endpoints/api/workspace/index.js273-349 server/swagger/openapi.json22-101
All workspace API endpoints follow consistent error handling patterns with appropriate HTTP status codes.
Success Response:
Error Response:
| Code | Meaning | Usage |
|---|---|---|
| 200 | Success | Successful operation completion |
| 400 | Bad Request | Invalid workspace slug, missing parameters |
| 403 | Forbidden | Invalid API key (handled by validApiKey middleware) |
| 500 | Internal Server Error | Unexpected server-side failures |
The error handling pattern is consistent across all endpoints server/endpoints/api/workspace/index.js97-100:
For chat endpoints specifically, errors return structured JSON with type: "abort" and close: true flags server/endpoints/api/workspace/index.js661-669
Sources: server/endpoints/api/workspace/index.js97-100 server/endpoints/api/workspace/index.js661-669 server/endpoints/api/workspace/index.js711-719
All workspace operations trigger telemetry and event logging for analytics and auditing purposes.
This metadata enables analysis of feature usage, provider distribution, and system configuration patterns. Implementation at server/endpoints/api/workspace/index.js85-92
Event logs provide an audit trail of API operations with contextual information. These logs can be queried via the admin API endpoints System and Admin API Endpoints.
Sources: server/endpoints/api/workspace/index.js85-96 server/endpoints/api/workspace/index.js697-708 server/endpoints/api/workspaceThread/index.js93-102
Refresh this wiki