Skip to main content
GET
JavaScript
The embeddable surfaces in a workspace. Each row carries a state, the agent binding in spec, and (with includeInfo) the hostname and agent name in info.

Filtering

agentId narrows the list to widgets bound to one agent, in either the canonical agent_… form or the external_id:<value> form. labels and sortOrder behave as they do on every list endpoint, and limit sets a page size the SDK iterator pages past on its own.
That is the question to ask before deleting an agent: which widgets stop working.

includeInfo costs rate limit

info carries dnsLabel, host, the bound agent’s name, and createdBy. Populating it counts more against your rate limit, so ask for it when you display the list, not when you poll it.

Create a widget

One hostname, one allowlist, one agent.

Get a widget

One widget, by wgt_… id or external ID.

List widget sessions

The sessions minted against these widgets.

Archive a widget

Stop the hostname without deleting the widget.

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"

Query Parameters

limit
integer<int32>

Maximum number of results to return.

cursor
string

Pagination cursor from previous response.

agentId
string

Filter to widgets bound to a specific agent. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

labels
string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

sortOrder
string

Sort order for results (asc or desc by creation time).

includeInfo
boolean

When true, the info field on each returned widget is populated. Requests with this flag count more against your rate limit.

Response

OK

List widgets response.

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.