Skip to main content
GET
JavaScript
Fetch a single widget. The id accepts the canonical wgt_… form or external_id:<value> if you set one at creation.

Read the hostname from info.host

info.dnsLabel is the single label; info.host is the full hostname browsers talk to. host is authoritative: read it, ship it to your frontend, and never assemble it from the label and a domain you hard-code. The domain is Cadenya’s to change. info also carries the bound agent as a bare reference (info.agent) and the profile that created the widget (info.createdBy).

Update a widget

Change the allowlist or the agent. Not the label.

List widget sessions

?widgetId= for this widget’s sessions.

Delete a widget

The hostname stops serving and sessions are revoked.

Use your own IDs

The external_id: form this endpoint accepts.

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.

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.