Skip to main content
GET
JavaScript
Fetch a single session by its wsess_… id or external_id:<value> form.

What info tells you

lastActiveAt is the field for “is this visitor still around”: token refreshes bump it even when no one is typing.

The token stays gone

spec.token is populated once, in the create response, and omitted on every read after. There is no recover-the-token endpoint. If the browser lost it, mint a new session and revoke the orphan.

Revoke a widget session

End this session before its expiry.

Delete a widget session

Remove the row and its secrets.

List widget sessions

All sessions, filterable four ways.

Create a widget session

Where the token appears, once.

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

Session ID. Accepts the canonical wsess_… form or the external_id:<value> form.

Response

OK

WidgetSession is a delegated, narrowed credential for one visitor's use of a widget, minted server-to-server by the customer's backend. The session carries all customer-asserted context — tenant, subject, labels, secrets — and every conversation (objective) created through the widget inherits it. The bearer token returned at mint is short-lived and refreshed at the widget host; the session row is what makes revocation possible.

metadata
object
required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

spec
object
required

WidgetSessionSpec is the configuration of a session, fixed at mint.

state
enum<string>
required
read-only

The current lifecycle state of the session. Output only. Sessions are created STATE_ACTIVE; use :revoke to end one early.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_EXPIRED,
STATE_REVOKED,
STATE_EXHAUSTED
info
object

WidgetSessionInfo provides read-only server-derived data about a session.

secrets
object[]
read-only

Names of the secrets attached to the session. Values are write-only: provided at creation, encrypted at rest, and interpolated into tool-call headers server-side — never returned by any API.