Create a widget
Bind an agent to a hostname. The server mints the DNS label; you bring the agent and the origin allowlist.
metadata.name and spec.agentId are required.
The hostname is server-made and immutable
The server generatesinfo.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.
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.
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.
Related
Create a widget session
Update a widget
Create an agent
List widgets
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
Create widget request.
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.
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.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
WidgetSpec is the user-provided configuration for a widget.
The current lifecycle state of the widget. Output only. Widgets are created STATE_ACTIVE; use the :archive and :unarchive actions to transition between states.
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_ARCHIVED WidgetInfo provides read-only server-derived data about a widget.