Skip to main content
PATCH
JavaScript
A 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. Change spec.agentId and:
In-flight conversations finish against the agent they started with. To force everyone onto the new agent now, update the widget and then revoke the old sessions.

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.

Create a widget

The fields this endpoint edits, explained at birth.

Revoke a widget session

Force old sessions off the previous agent.

Archive a widget

Stop serving without editing anything.

List widget sessions

See which sessions still carry the old 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"

id
string
required

Widget ID. Accepts the canonical wgt_… form or the external_id:<value> form.

Body

application/json

Update widget request.

metadata
object

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.

spec
object

WidgetSpec is the user-provided configuration for a widget.

updateMask
string<field-mask>

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.

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.