> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets API reference

> Hosts, authentication, session renewal, event streaming, and endpoints for the browser-facing Cadenya Widgets API.

The Widgets API is the API a browser uses to talk to a [Widget](/docs/guides/the-basics/widgets). 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](/docs/api-reference), 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`:

```text theme={null}
https://<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:

| Field | Meaning |
| - | - |
| `tokenExpiresAt` | When the current token stops authenticating requests. |
| `sessionExpiresAt` | The hard session deadline. No token outlives it. |

`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

| Client | Install |
| - | - |
| React UI kit | `npm install @cadenya/widgets-ui-react` · [GitHub](https://github.com/cadenya/widgets-ui-react) |
| TypeScript | `npm install @cadenya/widgets` · [GitHub](https://github.com/cadenya/widgets-sdk) |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.