Skip to main content
POST
CLI

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"

Body

application/json

Create widget session request.

spec
object
required

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

metadata
object

CreateOperationMetadata contains the user-provided fields for creating an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id) are excluded since they are set by the server.

secrets
object[]

Secrets to attach to the session.

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
secrets
object[]
required
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.

info
object

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