Skip to main content
POST
JavaScript
A widget is an embeddable chat surface bound to one agent. Each widget owns a globally unique hostname under the widgets domain, and one widget means one hostname, one origin allowlist, one agent binding. Browsers talk to that hostname with session tokens minted through widget sessions; they never hold your API key. Only metadata.name and spec.agentId are required.

The hostname is server-made and immutable

The server generates info.dnsLabel at creation and never changes it. The label has no relation to the widget’s wgt_… id, on purpose: the id is yours to reference, the label belongs to the edge. Read the full hostname from info.host and treat it as authoritative. Never construct it yourself.
The hostname can take up to a minute to become reachable while the edge propagates. Create the widget before you need it, not during the page load that embeds it.

originAllowlist is exact origins only

Every browser request is checked against the allowlist at the edge. An entry is a full origin: scheme, host, and optional port. No paths, no wildcard subdomains.
An empty allowlist means no browser origin can use the widget, which is a fine state while you configure it.

variationId pins a variation

By default every conversation runs through the agent’s variationSelectionMode, same as any objective. Set spec.variationId and every conversation on this widget runs that one variation instead, bypassing selection. The pin must belong to the widget’s agent. The staged rollout pattern: pin the known-good variation in production, let staging follow the selection mode, and promote by clearing the pin.

Create a widget session

Mint the token a browser uses against the widget host.

Update a widget

Re-point the agent or edit the allowlist. The label stays.

Create an agent

The thing the widget binds to.

List widgets

Every widget in the workspace, filterable by agent.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json

Create widget request.

metadata
object
required

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object
required

WidgetSpec is the user-provided configuration for a widget.

Response

OK

Widget is an embeddable chat surface bound to a single agent. Each widget owns a globally unique, immutable DNS label under the widgets domain (e.g. "k7m2xq9fp4wn.widgets.cadenya.com"): one widget = one hostname = one origin allowlist = one agent binding. Browsers talk to the widget host with session bearer tokens minted server-side via WidgetSessionService.

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

spec
object
required

WidgetSpec is the user-provided configuration for a widget.

state
enum<string>
required
read-only

The current lifecycle state of the widget. Output only. Widgets are created STATE_ACTIVE; use the :archive and :unarchive actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_ARCHIVED
info
object

WidgetInfo provides read-only server-derived data about a widget.