Workspace API Endpoints — Chat, Manage, and Embed

Workspaces are the core organisational unit in AnythingLLM. Each workspace holds its own set of embedded documents, LLM settings, chat history, and threads. The API lets you manage every aspect of a workspace programmatically — from initial creation and document embedding to running chat conversations and performing direct vector similarity searches. All requests must include a valid Bearer token in the Authorization header.

All API endpoints are prefixed with /api. For a self-hosted instance the full base URL is typically http://localhost:3001/api/v1/....

POST /v1/workspace/new

Create a new workspace. Returns the created workspace object on success.

Body Parameters

name

string

required

Display name for the new workspace.

similarityThreshold

number

Minimum vector-similarity score (0–1) that a document chunk must reach before it is included in a response context. Defaults to 0.25.

openAiTemp

number

LLM temperature override for this workspace (0–1). Leave null to use the system default.

openAiHistory

integer

Number of previous chat turns to include in the LLM context window. Default 20.

openAiPrompt

string

Custom system prompt applied to every conversation in this workspace.

queryRefusalResponse

string

Custom message returned when the workspace has no relevant context to answer a query-mode question.

chatMode

string

Default chat mode: "chat" (uses general LLM knowledge + documents) or "query" (documents only).

topN

integer

Maximum number of document chunks to retrieve per query. Default 4.

Response Fields

workspace

object

Show workspace fields

integer

Database row ID.

name

string

Workspace display name.

slug

string

URL-safe unique identifier derived from the name.

createdAt

string

ISO timestamp of creation.

openAiTemp

number | null

Temperature setting.

openAiHistory

integer

Chat history turns.

openAiPrompt

string | null

Custom system prompt.

lastUpdatedAt

string

ISO timestamp of last update.

message

string

"Workspace created" on success.

curl -X POST https://your-instance.com/api/v1/workspace/new \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "similarityThreshold": 0.7,
    "openAiTemp": 0.4,
    "openAiHistory": 20,
    "chatMode": "chat",
    "topN": 4
  }'

GET /v1/workspaces

Return a list of all workspaces on the instance.

Response Fields

workspaces

array

Array of workspace objects. Each object contains the same fields as the create response plus a threads array.

curl https://your-instance.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/workspace/{slug}

Retrieve a single workspace by its unique slug, including embedded documents and threads.

Path Parameters

slug

string

required

Unique URL slug of the workspace (e.g. product-docs).

Response Fields

workspace

array

Single-element array containing the full workspace object with documents and threads arrays.

curl https://your-instance.com/api/v1/workspace/product-docs \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/workspace/{slug}/update

Update one or more settings on an existing workspace. Only the fields you include will be changed.

Path Parameters

slug

string

required

Unique slug of the workspace to update.

Body Parameters

name

string

New display name.

openAiTemp

number

Updated temperature (0–1).

openAiHistory

integer

Number of history turns to retain.

openAiPrompt

string

Updated system prompt.

Response Fields

workspace

object

Updated workspace object including all current settings and embedded documents.

message

string | null

Error string if the update failed, otherwise null.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "openAiTemp": 0.2,
    "openAiPrompt": "Answer in a concise, technical tone."
  }'

DELETE /v1/workspace/{slug}

Permanently delete a workspace and all its embedded document associations. This does not delete the source documents from the library.

Path Parameters

slug

string

required

Unique slug of the workspace to delete.

curl -X DELETE https://your-instance.com/api/v1/workspace/product-docs \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/workspace/{slug}/chats

Return the full chat history for a workspace, optionally filtered by an external session identifier.

Path Parameters

slug

string

required

Unique slug of the workspace.

Query Parameters

apiSessionId

string

Filter results to a specific external session ID passed during chat requests.

limit

integer

Maximum number of messages to return. Default 100.

orderBy

string

Sort order: "asc" or "desc". Defaults to ascending.

Response Fields

history

array

Show history message fields

role

string

"user" or "assistant".

content

string

Message text.

sentAt

integer

Unix timestamp of the message.

sources

array

Array of source document snippets (assistant messages only).

curl "https://your-instance.com/api/v1/workspace/product-docs/chats?limit=50&orderBy=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/workspace/{slug}/update-embeddings

Add or remove documents from a workspace. Document paths are relative to the top-level documents storage directory (i.e. omit the leading documents/ prefix).

Path Parameters

slug

string

required

Unique slug of the workspace.

Body Parameters

adds

array

Array of document path strings to embed into the workspace. Example: ["custom-documents/my-pdf.pdf-hash.json"].

deletes

array

Array of document path strings to remove from the workspace embeddings.

Response Fields

workspace

object

Updated workspace object with the new documents array reflecting the changes.

message

string | null

null on success or an error description.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/update-embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adds": ["custom-documents/release-notes.pdf-abc123.json"],
    "deletes": ["custom-documents/old-notes.txt-def456.json"]
  }'

POST /v1/workspace/{slug}/update-pin

Toggle the pinned state of a specific document inside a workspace. Pinned documents are always injected into the LLM context regardless of vector search results.

Path Parameters

slug

string

required

Unique slug of the workspace.

Body Parameters

docPath

string

required

The document path as stored in the workspace (e.g. custom-documents/my-pdf.pdf-hash.json).

pinStatus

boolean

required

true to pin the document, false to unpin it.

Response Fields

message

string

"Pin status updated successfully" on success.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/update-pin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docPath": "custom-documents/release-notes.pdf-abc123.json",
    "pinStatus": true
  }'

POST /v1/workspace/{slug}/chat

Send a message to a workspace and receive a complete (non-streaming) response. Supports chat, query, and automatic modes, as well as inline image and document attachments.

Path Parameters

slug

string

required

Unique slug of the workspace to chat with.

Body Parameters

message

string

required

The user’s message or question.

mode

string

Conversation mode:

"chat" — uses LLM general knowledge plus embedded documents with rolling history.
"query" — only answers from embedded documents; ignores chat history.
"automatic" — uses tool-calling when the LLM provider supports it, without needing to invoke @agent. Defaults to "chat".

sessionId

string

An arbitrary external identifier used to partition chat history. Useful for multi-tenant deployments where you want per-user history.

attachments

array

Show attachment object fields

name

string

Filename of the attachment.

mime

string

MIME type. Use "application/anythingllm-document" to have the file parsed as text before injection. Any other MIME is passed directly to the LLM as an image.

contentString

string

Base64-encoded data URI of the file content.

reset

boolean

Set to true to clear the existing chat history for this session before sending. Default false.

Response Fields

string

Unique ID of the chat exchange.

type

string

"textResponse" on success or "abort" on failure.

textResponse

string

The LLM’s response text.

sources

array

Array of source document chunks used to generate the answer. Each item contains a title (document filename) and a chunk (the relevant text snippet).

boolean

Always true for non-streaming responses.

error

string | null

null on success, or a description of the failure.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What changed in the latest release?",
    "mode": "query",
    "sessionId": "user-session-42"
  }'

POST /v1/workspace/{slug}/stream-chat

Send a message and receive the response as a Server-Sent Events (SSE) stream. Each event is a JSON object with a textResponseChunk type. The final event carries "close": true and the full sources array.

Path Parameters

slug

string

required

Unique slug of the workspace to chat with.

Body Parameters

Identical to POST /v1/workspace/{slug}/chat — message, mode, sessionId, attachments, and reset.

Response

The response Content-Type is text/event-stream. Each data: line contains a JSON object:

string

Shared ID for all chunks in this response.

type

string

"textResponseChunk" for content or "abort" on error.

textResponse

string

Text fragment for this chunk.

sources

array

Populated only in the final chunk (close: true). Each item contains a title and chunk field.

boolean

true signals the end of the stream.

error

string | null

Error string or null.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/stream-chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Summarise the architecture overview.",
    "mode": "chat"
  }'

POST /v1/workspace/{slug}/vector-search

Perform a raw vector similarity search against the workspace’s embedded documents without invoking the LLM. Returns the most similar document chunks along with their distance scores.

Path Parameters

slug

string

required

Unique slug of the workspace to search.

Body Parameters

query

string

required

The natural-language query string to embed and search with.

topN

integer

Number of results to return. Default 4.

scoreThreshold

number

Minimum similarity score (0–1) a chunk must have to appear in results.

Response Fields

results

array

Show result object fields

string

Unique vector ID of the chunk.

text

string

Raw text content of the document chunk.

metadata

object

Document metadata including title, url, author, wordCount, and tokenCount.

distance

number

Raw vector distance (lower = more similar).

score

number

Normalised similarity score (higher = more similar).

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/vector-search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication flow",
    "topN": 5,
    "scoreThreshold": 0.6
  }'

Workspace Thread Endpoints

Threads are isolated conversation contexts inside a workspace. They share the workspace’s documents and settings but maintain independent chat histories.

POST /v1/workspace/{slug}/thread/new

Create a new thread inside a workspace.

Path Parameters

slug

string

required

Unique slug of the parent workspace.

Body Parameters

name

string

Display name for the thread. Auto-generated if omitted.

slug

string

Custom slug for the thread. Auto-generated if omitted.

userId

integer

Associate the thread with a specific user ID (multi-user mode).

Response Fields

thread

object

Show thread fields

integer

Thread database ID.

name

string

Thread display name.

slug

string

Thread slug used in subsequent requests.

user_id

integer | null

Associated user ID.

workspace_id

integer

Parent workspace ID.

message

string | null

null on success or an error description.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/thread/new \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Release Q3 Discussion"}'

POST /v1/workspace/{slug}/thread/{threadSlug}/update

Update the display name of an existing thread.

Path Parameters

slug

string

required

Workspace slug.

threadSlug

string

required

Thread slug to update.

Body Parameters

name

string

required

New display name for the thread.

Response Fields

thread

object

Updated thread object with id, name, slug, user_id, and workspace_id.

message

string | null

null on success or an error description.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/thread/release-q3-discussion/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Release Notes Review"}'

DELETE /v1/workspace/{slug}/thread/{threadSlug}

Permanently delete a thread and its chat history.

Path Parameters

slug

string

required

Workspace slug.

threadSlug

string

required

Thread slug to delete.

curl -X DELETE https://your-instance.com/api/v1/workspace/product-docs/thread/release-q3-discussion \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/workspace/{slug}/thread/{threadSlug}/chats

Retrieve the full message history for a specific thread.

Path Parameters

slug

string

required

Workspace slug.

threadSlug

string

required

Thread slug.

Response Fields

history

array

Array of {role, content, sentAt, sources} message objects — same schema as workspace-level chats.

curl https://your-instance.com/api/v1/workspace/product-docs/thread/release-q3-discussion/chats \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/workspace/{slug}/thread/{threadSlug}/chat

Send a non-streaming message to a workspace thread.

Path Parameters

slug

string

required

Workspace slug.

threadSlug

string

required

Thread slug.

Body Parameters

message

string

required

The user message.

mode

string

"chat" or "query". Default "chat".

userId

integer

Associate this message with a user ID.

attachments

array

Inline file attachments — same structure as workspace chat.

reset

boolean

Clear thread history before this message. Default false.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/thread/release-q3-discussion/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the breaking changes?",
    "mode": "query"
  }'

POST /v1/workspace/{slug}/thread/{threadSlug}/stream-chat

Send a streaming SSE message to a workspace thread. Response format and parameters are identical to the workspace-level stream-chat endpoint.

Path Parameters

slug

string

required

Workspace slug.

threadSlug

string

required

Thread slug.

curl -X POST https://your-instance.com/api/v1/workspace/product-docs/thread/release-q3-discussion/stream-chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Summarise the thread so far.",
    "mode": "chat"
  }'

Overview

Endpoints

Documentation Index

​POST /v1/workspace/new

​Body Parameters

​Response Fields

​GET /v1/workspaces

​Response Fields

​GET /v1/workspace/{slug}

​Path Parameters

​Response Fields

​POST /v1/workspace/{slug}/update

​Path Parameters

​Body Parameters

​Response Fields

​DELETE /v1/workspace/{slug}

​Path Parameters

​GET /v1/workspace/{slug}/chats

​Path Parameters

​Query Parameters

​Response Fields

​POST /v1/workspace/{slug}/update-embeddings

​Path Parameters

​Body Parameters

​Response Fields

​POST /v1/workspace/{slug}/update-pin

​Path Parameters

​Body Parameters

​Response Fields

​POST /v1/workspace/{slug}/chat

​Path Parameters

​Body Parameters

​Response Fields

​POST /v1/workspace/{slug}/stream-chat

​Path Parameters

​Body Parameters

​Response

​POST /v1/workspace/{slug}/vector-search

​Path Parameters

​Body Parameters

​Response Fields

​Workspace Thread Endpoints

​POST /v1/workspace/{slug}/thread/new

​Path Parameters

​Body Parameters

​Response Fields

​POST /v1/workspace/{slug}/thread/{threadSlug}/update

​Path Parameters

​Body Parameters

​Response Fields

​DELETE /v1/workspace/{slug}/thread/{threadSlug}

​Path Parameters

​GET /v1/workspace/{slug}/thread/{threadSlug}/chats

​Path Parameters

​Response Fields

​POST /v1/workspace/{slug}/thread/{threadSlug}/chat

​Path Parameters

​Body Parameters

​POST /v1/workspace/{slug}/thread/{threadSlug}/stream-chat

​Path Parameters

Build docs developers (and LLMs) love

POST /v1/workspace/new

Body Parameters

Response Fields

GET /v1/workspaces

Response Fields

GET /v1/workspace/{slug}

Path Parameters

Response Fields

POST /v1/workspace/{slug}/update

Path Parameters

Body Parameters

Response Fields

DELETE /v1/workspace/{slug}

Path Parameters

GET /v1/workspace/{slug}/chats

Path Parameters

Query Parameters

Response Fields

POST /v1/workspace/{slug}/update-embeddings

Path Parameters

Body Parameters

Response Fields

POST /v1/workspace/{slug}/update-pin

Path Parameters

Body Parameters

Response Fields

POST /v1/workspace/{slug}/chat

Path Parameters

Body Parameters

Response Fields

POST /v1/workspace/{slug}/stream-chat

Path Parameters

Body Parameters

Response

POST /v1/workspace/{slug}/vector-search

Path Parameters

Body Parameters

Response Fields

Workspace Thread Endpoints

POST /v1/workspace/{slug}/thread/new

Path Parameters

Body Parameters

Response Fields

POST /v1/workspace/{slug}/thread/{threadSlug}/update

Path Parameters

Body Parameters

Response Fields

DELETE /v1/workspace/{slug}/thread/{threadSlug}

Path Parameters

GET /v1/workspace/{slug}/thread/{threadSlug}/chats

Path Parameters

Response Fields

POST /v1/workspace/{slug}/thread/{threadSlug}/chat

Path Parameters

Body Parameters

POST /v1/workspace/{slug}/thread/{threadSlug}/stream-chat

Path Parameters