Skip to main content
The Widgets API is the API a browser uses to talk to a Widget. It covers conversations, messages, tool calls, and the live event stream. Endpoint pages come from the Widgets API OpenAPI specification and define each request and response. The Widgets API never accepts a Cadenya API key. Your backend mints a Widget Session with the Cadenya API, then hands the browser the session’s token and host.

​
Base URL

Each Widget has its own host. Prefix API paths with the host from the Widget Session’s info.host:
A host looks like adbtaawrmh4h.widgets.cadenya.com. Read it from the session response. Do not build it from the Widget ID.

​
Origins

The Widget host only answers requests from origins on the Widget’s originAllowlist. The allowlist takes exact origins, such as https://app.example.com or http://localhost:3000. It does not accept wildcards.

​
Authentication

Send the Widget Session token as a bearer token in the Authorization header: Authorization: Bearer <token>. The token carries the session’s scope: the Widget, the Agent, the tenant, and the subject. Requests take no workspace, tenant, or subject parameters. A conversation outside the token’s scope returns 404, the same as a conversation that does not exist. GET /v1/config is the only route that needs no token. It returns the Widget’s presentation config, creates no session, and records no billable event.

​
Session lifetime

A Widget Session has two deadlines: POST /v1/workspaces/{workspaceId}/session:renew returns a fresh token for the same session. It takes the current bearer token and the session’s workspace ID, and no session ID. Renewal accepts a token up to 60 seconds past its expiry. It never extends sessionExpiresAt, and a revoked, expired, or exhausted session cannot renew. When renewal fails, mint a new session from your backend.

​
Event stream

GET /v1/conversations/{id}/events:stream returns server-sent events. Each durable event has an ID. Pass the last ID you received in the Last-Event-ID header to resume after a reconnect. Heartbeat and control frames carry no ID. An expired token leaves an open stream running. Revocation, hard expiry, or exhaustion closes the stream within 10 seconds. Before it closes, the server attempts a session-ended event whose data is a Status with WidgetSessionErrorInfo in its details.

​
Bare tool calls

When the Agent calls a Bare tool, the conversation waits for the page to supply the result. Send it with POST /v1/conversations/{id}/tool_calls/{toolCallId}:setContent. The result reaches the conversation as a toolResult event. The browser sees a tool call’s arguments only when the Tool Set enables widget argument exposure.

​
Errors

Errors return a Status object with a code, a message, and details. Session errors include a WidgetSessionErrorInfo entry that names the reason, such as an expired token.

​
List requests

GET /v1/conversations accepts limit and cursor. The response contains items and pagination.nextCursor, newest activity first. Pass nextCursor as cursor to request the next page. An empty cursor marks the end of the result set.

​
Clients

Browse the endpoint groups in the sidebar for operation-specific parameters and schemas.