Embed Widget API — Chat Widget Configuration Guide

AnythingLLM’s Embed feature lets you drop a chat widget into any website by generating a JavaScript snippet tied to a workspace. Each embed has its own configuration — chat mode, domain allowlist, rate limits, and toggle switches that let end-users override the model, temperature, or system prompt. The Embeds API gives you full programmatic control over these configurations and provides read access to the conversations that happen through embedded widgets.

Embed configurations are identified by a UUID. When you create an embed the response includes the uuid field — store this value, as you will need it for all subsequent read, update, and delete operations.

GET /v1/embed

Return a list of every embed configuration on the instance, including a chat message count and the associated workspace name.

Response Fields

embeds

array

Show embed object fields

integer

Database row ID.

uuid

string

Unique embed identifier (used in the widget script src).

enabled

boolean

Whether the embed is currently active.

chat_mode

string

"chat" or "query".

createdAt

string

ISO timestamp of creation.

workspace

object

Nested workspace summary with id and name.

chat_count

integer

Total number of chat messages sent through this embed.

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

POST /v1/embed/new

Create a new embed configuration tied to a workspace. Returns the full embed object on success.

Body Parameters

workspace_slug

string

required

Slug of the workspace this embed will use for chat context.

chat_mode

string

Conversation mode for the widget: "chat" (general knowledge + documents) or "query" (documents only). Default "chat".

allowlist_domains

array

Array of domain strings that are permitted to load the widget. Leave empty to allow any domain. Example: ["example.com", "app.example.com"].

allow_model_override

boolean

Allow the embedded widget to accept a model parameter that overrides the workspace’s default LLM. Default false.

allow_temperature_override

boolean

Allow the widget to accept a temperature override. Default false.

allow_prompt_override

boolean

Allow the widget to accept a custom system prompt override. Default false.

max_chats_per_day

integer

Maximum total chat messages this embed will process across all sessions in a 24-hour period. null for unlimited.

max_chats_per_session

integer

Maximum chat messages per individual session. null for unlimited.

Response Fields

embed

object

Show embed object fields

integer

Database row ID.

uuid

string

Unique embed UUID — use this in the widget script.

enabled

boolean

Whether the embed is active.

chat_mode

string

Assigned chat mode.

allowlist_domains

array

Permitted domain list.

allow_model_override

boolean

Model override flag.

allow_temperature_override

boolean

Temperature override flag.

allow_prompt_override

boolean

Prompt override flag.

max_chats_per_day

integer | null

Daily chat cap.

max_chats_per_session

integer | null

Per-session chat cap.

createdAt

string

ISO creation timestamp.

workspace_slug

string

Slug of the linked workspace.

error

string | null

null on success or an error description.

curl -X POST https://your-instance.com/api/v1/embed/new \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_slug": "product-docs",
    "chat_mode": "query",
    "allowlist_domains": ["example.com"],
    "allow_model_override": false,
    "allow_temperature_override": false,
    "allow_prompt_override": false,
    "max_chats_per_day": 500,
    "max_chats_per_session": 20
  }'

GET /v1/embed/{embedUuid}/chats

Retrieve all chat messages sent through a specific embed, across all user sessions.

Path Parameters

embedUuid

string

required

UUID of the embed to inspect.

Response Fields

chats

array

Show chat object fields

integer

Chat message database ID.

session_id

string

UUID identifying the anonymous session the message belongs to.

prompt

string

The user’s message.

response

string

The assistant’s reply.

createdAt

string

ISO timestamp of the exchange.

curl https://your-instance.com/api/v1/embed/embed-uuid-1/chats \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/embed/{embedUuid}/chats/{sessionUuid}

Retrieve the chat history for a specific embed session. Useful for reviewing a single anonymous user’s conversation.

Path Parameters

embedUuid

string

required

UUID of the embed.

sessionUuid

string

required

UUID of the session to retrieve.

Response Fields

chats

array

Show chat object fields

integer

Message database ID.

prompt

string

User’s message.

response

string

Assistant’s reply.

createdAt

string

ISO timestamp.

curl https://your-instance.com/api/v1/embed/embed-uuid-1/chats/session-uuid-abc \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/embed/{embedUuid}

Update the configuration of an existing embed. All fields are optional — only the ones you supply will be changed.

Path Parameters

embedUuid

string

required

UUID of the embed to update.

Body Parameters

enabled

boolean

Enable or disable the embed widget.

chat_mode

string

Update the conversation mode: "chat" or "query".

allowlist_domains

array

Replace the domain allowlist.

allow_model_override

boolean

Toggle model override permission.

allow_temperature_override

boolean

Toggle temperature override permission.

allow_prompt_override

boolean

Toggle prompt override permission.

max_chats_per_day

integer

Update the daily chat cap.

max_chats_per_session

integer

Update the per-session chat cap.

Response Fields

success

boolean

Whether the update was applied.

error

string | null

null on success or an error description.

curl -X POST https://your-instance.com/api/v1/embed/embed-uuid-1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "max_chats_per_day": 1000,
    "allowlist_domains": ["example.com", "beta.example.com"]
  }'

DELETE /v1/embed/{embedUuid}

Permanently delete an embed configuration. The widget script on any site still referencing this UUID will stop functioning immediately.

Deleting an embed is permanent and cannot be undone. Any chat history associated with the embed will also be removed.

Path Parameters

embedUuid

string

required

UUID of the embed to delete.

Response Fields

success

boolean

Whether the deletion was successful.

error

string | null

null on success or an error message.

curl -X DELETE https://your-instance.com/api/v1/embed/embed-uuid-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Overview

Endpoints

Embed Widget API — Chat Widget Configuration Guide

GET /v1/embed

Response Fields

POST /v1/embed/new

Body Parameters

Response Fields

GET /v1/embed/{embedUuid}/chats

Path Parameters

Response Fields

GET /v1/embed/{embedUuid}/chats/{sessionUuid}

Path Parameters

Response Fields

POST /v1/embed/{embedUuid}

Path Parameters

Body Parameters

Response Fields

DELETE /v1/embed/{embedUuid}

Path Parameters

Response Fields

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /v1/embed

​Response Fields

​POST /v1/embed/new

​Body Parameters

​Response Fields

​GET /v1/embed/{embedUuid}/chats

​Path Parameters

​Response Fields

​GET /v1/embed/{embedUuid}/chats/{sessionUuid}

​Path Parameters

​Response Fields

​POST /v1/embed/{embedUuid}

​Path Parameters

​Body Parameters

​Response Fields

​DELETE /v1/embed/{embedUuid}

​Path Parameters

​Response Fields

Build docs developers (and LLMs) love

GET /v1/embed

Response Fields

POST /v1/embed/new

Body Parameters

Response Fields

GET /v1/embed/{embedUuid}/chats

Path Parameters

Response Fields

GET /v1/embed/{embedUuid}/chats/{sessionUuid}

Path Parameters

Response Fields

POST /v1/embed/{embedUuid}

Path Parameters

Body Parameters

Response Fields

DELETE /v1/embed/{embedUuid}

Path Parameters

Response Fields