Update a widget
Edit the name, allowlist, agent binding, or variation pin. The DNS label never changes.
PATCH on the widget’s metadata and spec. The DNS label and hostname are immutable: no update renames a widget’s hostname, ever. If you need a different hostname, that is a new widget.
Re-pointing the agent only affects new sessions
A session copies the widget’s agent at mint and keeps it for life. Changespec.agentId and:
Allowlist edits take effect at the edge
originAllowlist replaces as a whole; there is no append. Send the full list you want. Removing an origin cuts off embeds on that origin as the edge picks up the change.
Related
Create a widget
Revoke a widget session
Archive a widget
List widget sessions
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Widget ID. Accepts the canonical wgt_… form or the external_id:<value> form.
Body
Update widget request.
UpdateResourceMetadata contains the user-provided fields for updating 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.
Fields to update.
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.