Skip to main content
A web widget is the embeddable configuration that connects a published agent version to your website. The API has two parts: authenticated management endpoints under /core/web-widgets that you call from your backend to create and configure widgets, and unauthenticated public runtime endpoints under /core/public/web-widgets that the embedded widget calls from the browser to start conversations. For the product walkthrough and the embed snippet, see /web-widgets/overview. For domain restrictions, see /web-widgets/allowed-domains-and-security.

​
Authentication

The management endpoints require a token with the right scope. Use an org API key (ak_) or a user PAT (pat_): 
Authorization: Bearer <token>
X-Anyreach-Org: <organization_id>   # only required for pat_ tokens
ScopeGrants
web_widgets:readList and read widgets
web_widgets:manageCreate, update, delete, and auto-brand widgets
Read endpoints accept either scope. Write endpoints (POST, PUT, DELETE, auto-brand) require web_widgets:manage.
The public runtime endpoints are unauthenticated and resolve the organization from the widget id in the path. They are meant to be called from the browser by the embedded widget. Never send a PAT, API key, or X-Anyreach-Org header from browser code.

​
Management endpoints

All paths below are prefixed with /core/web-widgets.
MethodPathScopeDescription
GET/core/web-widgetsweb_widgets:readList widgets
POST/core/web-widgetsweb_widgets:manageCreate a widget
GET/core/web-widgets/{id}web_widgets:readGet one widget
PUT/core/web-widgets/{id}web_widgets:manageUpdate a widget
DELETE/core/web-widgets/{id}web_widgets:manageDelete a widget (returns 204)
POST/core/web-widgets/{id}/auto-brandweb_widgets:manageFetch brand data for a domain

​
Widget object

Every read and write endpoint returns the widget object.
FieldTypeDescription
idstringWidget identifier (used in the embed and in public paths)
organization_idstringOwning organization
agent_idstringAgent the widget serves
agent_version_idstringThe specific agent version the widget runs
domainsstring[]Domains allowed to embed and call the widget
publishedbooleanWhether the widget is live
configobjectWidget appearance and behavior configuration
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
List widgets

GET /core/web-widgets Returns an array of widgets. All query parameters are optional.
ParameterTypeDescription
agent_idstringFilter by agent
agent_version_idstringFilter by agent version
publishedbooleanFilter by published state
created_afterdatetimeCreated at or after
created_beforedatetimeCreated at or before
updated_afterdatetimeUpdated at or after
updated_beforedatetimeUpdated at or before
limitintegerPage size
cursorstringPagination cursor

​
Create a widget

POST /core/web-widgets The body sets the agent and version the widget runs. organization_id is taken from your token, not the body.
FieldTypeDefaultDescription
agent_idstringrequiredAgent to serve
agent_version_idstringrequiredAgent version to run
domainsstring[][]Allowed embed domains
publishedbooleanfalseWhether the widget is live
configobject{}Widget configuration
curl -X POST https://api.anyreach.ai/core/web-widgets \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_...",
    "agent_version_id": "av_...",
    "domains": ["app.example.com"],
    "published": true
  }'
The widget runs whatever agent_version_id you give it. Point it at a published agent version so the embedded widget can dispatch real conversations. See /web-widgets/overview for how versions are published.

​
Update a widget

PUT /core/web-widgets/{id} Send only the fields you want to change. agent_id, agent_version_id, domains, published, and config are all optional and replace the stored value when present.

​
Delete a widget

DELETE /core/web-widgets/{id} Returns 204 No Content on success.

​
Auto-brand

POST /core/web-widgets/{id}/auto-brand Fetches brand data (colors, logos, and related assets) for a domain so you can pre-fill widget styling. The widget must exist.
FieldTypeDescription
domainstringDomain to look up. Protocol, www., and trailing slash are stripped automatically
Returns the resolved brand object. Responds with 404 if no brand is found for the domain.

​
Public runtime endpoints

These power the embedded widget in the browser. They are unauthenticated: the organization is resolved from the widget id in the path, and the conversation channel is always WEBRTC. All paths are prefixed with /core/public/web-widgets.
MethodPathDescription
GET/core/public/web-widgets/{id}Fetch widget config for rendering
POST/core/public/web-widgets/{id}/conversationsCreate or resume a conversation
GET/core/public/web-widgets/{id}/conversationsList a visitor’s conversations
POST/core/public/web-widgets/{id}/conversations/{conversation_id}/feedbackSubmit post-conversation feedback

​
Get widget config

GET /core/public/web-widgets/{id} Returns the same widget object as the management endpoints. The embedded widget uses it to render appearance and behavior.

​
Create or resume a conversation

POST /core/public/web-widgets/{id}/conversations Starts a new WEBRTC conversation, or resumes an existing one when conversation_id is set. The response carries the LiveKit connection_details the browser uses to join the call.
FieldTypeDescription
user_idstringVisitor identifier. Required
custom_metadataobjectOptional metadata stored on the conversation
conversation_idstringExisting conversation to resume. When omitted, a new conversation is created
When resuming, the conversation must belong to this widget or the request returns 403; an unknown conversation_id returns 404. The response is a JSON object:
FieldTypeDescription
conversationobjectThe created or resumed conversation
connection_detailsobjectLiveKit connection info (url, token, room) for joining the WebRTC session
capabilitiesobjectsupportsVideoInput and supportsScreenShare, derived from the agent’s vision configuration

​
List a visitor’s conversations

GET /core/public/web-widgets/{id}/conversations Lists conversations scoped to this widget. Defaults to the WEBRTC channel. All query parameters are optional.
ParameterTypeDescription
user_idstringFilter to one visitor
channelstringConversation channel (defaults to WEBRTC)
idsstringComma-separated conversation IDs
limitintegerPage size
cursorstringPagination cursor

​
Submit feedback

POST /core/public/web-widgets/{id}/conversations/{conversation_id}/feedback Stores post-conversation feedback on the conversation. The conversation must already exist and belong to the widget, and the widget must have a feedback form configured.
FieldTypeDescription
dataobjectFeedback field values keyed by field id
Only keys that match the widget’s configured feedback-form field ids are stored; others are dropped. The endpoint enforces:
LimitValue
Max payload size16 KB (serialized JSON)
Submissions per conversationOne — a second submission returns 409
Returns { "status": "ok" } on success. It returns 400 if the widget collects no feedback or no valid fields were submitted, and 413 if the payload is too large.

Web widgets

Configure and embed a widget on your site.

Allowed domains and security

Restrict which sites can embed and run a widget.