Skip to main content
POST
JavaScript
The pause button. Archiving moves a widget to STATE_ARCHIVED: the hostname stops serving at the edge, existing sessions are revoked, and no new sessions can be minted. Unlike delete, the DNS label stays reserved for this widget.

What archive touches

The session revocation is the part to plan around: it is the same terminal revocation as revoke, and unarchiving does not resurrect the sessions. Visitors get fresh sessions when your backend mints them.

Unarchive a widget

Same hostname, back in service.

Delete a widget

The permanent version. The label never returns.

Create a widget session

What visitors need again after unarchive.

List widgets

Archived widgets stay visible in the list.

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

Archive widget request.

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.