> ## 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. # List conversation events > Returns a conversation's event history for initial render, oldest first. Live updates arrive on the event stream. ## OpenAPI ````yaml /widgets-api-spec.yml get /v1/conversations/{id}/events openapi: 3.1.0 info: title: Cadenya Widgets API description: >- Browser-facing API for the embeddable Cadenya chat widget. The customer's backend authenticates the visitor and creates the initial session. The browser renews that same session through RenewWidgetSession using its existing bearer token and required workspace ID, with no session ID in the request. Both return tokenExpiresAt and sessionExpiresAt; renewal never extends the session deadline. Renewal requires a valid token with 60 seconds of clock-skew tolerance; hard session expiry has no tolerance. Management credentials remain server-side. Terminal session errors never create a replacement. The only unauthenticated route is the widget config. version: '1.0' servers: - url: https://{widgetHost} description: The Widget host returned in a Widget Session's info.host variables: widgetHost: default: adbtaawrmh4h.widgets.cadenya.com security: - bearerAuth: [] tags: - name: WidgetConfigService description: |- Serves the widget's presentation config. The only unauthenticated surface: the widget is identified by the hostname and the edge enforces the origin allowlist; no session or token is required. - name: WidgetConversationEventStreamsService description: |- Server-streaming events over SSE. A separate service so deployments can route it around the JSON transcoder to a dedicated stream server — the transcoder cannot produce text/event-stream. - name: WidgetConversationService description: |- Conversations between the session's visitor and the widget's agent. All routes are token-implicit: scope comes entirely from the bearer's claims, and a conversation outside that scope 404s indistinguishably from one that does not exist. - name: WidgetSessionService description: |- Renews the caller's existing session token. Session identity comes only from the verified bearer token; no caller-supplied ID selects a session. paths: /v1/conversations/{id}/events: get: tags: - WidgetConversationService - Conversations summary: List conversation events description: >- Returns a conversation's event history for initial render, oldest first. Live updates arrive on the event stream. operationId: WidgetConversationService_ListConversationEvents parameters: - name: id in: path description: Conversation ID. required: true schema: type: string - name: limit in: query description: Maximum number of results to return. schema: type: integer format: int32 - name: cursor in: query description: Pagination cursor from previous response. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListConversationEventsResponse' '401': description: >- Unauthenticated. TOKEN_EXPIRED identifies verified access-token expiry at or beyond exp + 60 seconds before execution. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. Never retry renewal recursively. Missing, malformed, or invalid tokens do not authorize renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '403': description: >- Permission denied. SESSION_REVOKED or SESSION_EXPIRED is terminal. Management authorization failures never trigger visitor-token renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '429': description: >- Resource exhausted. SESSION_EXHAUSTED is terminal; rate limiting uses a distinct reason and may include Retry-After. content: application/json: schema: $ref: '#/components/schemas/Status' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: typescript label: TypeScript source: |- import CadenyaWidgets from '@cadenya/widgets'; const client = new CadenyaWidgets(); const page = await client.conversations.listEvents('_123'); for await (const item of page) { console.log(item); } - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcadenyawidgets \"go.cadenya.com/cadenya-widgets-go\"\n)\n\nfunc main() {\n\tclient, err := cadenyawidgets.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenyawidgets.ConversationListEventsParams{}\n\tresult, err := client.Conversations().ListEvents(ctx, \"_123\", params)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Printf(\"%+v\\n\", result)\n}" - lang: python label: Python source: |- from cadenya_widgets import CadenyaWidgets with CadenyaWidgets() as client: for item in client.conversations.list_events("_123"): print(item) - lang: ruby label: Ruby source: |- require "cadenya-widgets" client = CadenyaWidgets::Client.new client.conversations.list_events("_123").each do |item| puts item.inspect end - lang: bash label: CLI source: cadenya-widgets conversations list-events _123 - lang: shell label: curl source: |- curl --request GET \ --url '/v1/conversations/_123/events' \ --header "Authorization: Bearer ${CADENYAWIDGETS_API_KEY}" components: schemas: ListConversationEventsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/WidgetEvent' pagination: $ref: '#/components/schemas/Page' description: List conversation events response. Ordered oldest first. Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: anyOf: - $ref: '#/components/schemas/WidgetSessionErrorInfo' - $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). WidgetEvent: oneOf: - $ref: '#/components/schemas/WidgetEvent_UserMessage' - $ref: '#/components/schemas/WidgetEvent_AssistantMessage' - $ref: '#/components/schemas/WidgetEvent_ToolApprovalRequested' - $ref: '#/components/schemas/WidgetEvent_ToolApproved' - $ref: '#/components/schemas/WidgetEvent_ToolDenied' - $ref: '#/components/schemas/WidgetEvent_ToolCalled' - $ref: '#/components/schemas/WidgetEvent_ToolResult' - $ref: '#/components/schemas/WidgetEvent_ToolError' - $ref: '#/components/schemas/WidgetEvent_Error' - $ref: '#/components/schemas/WidgetEvent_Cancelled' - $ref: '#/components/schemas/WidgetEvent_TimedOut' - $ref: '#/components/schemas/WidgetEvent_Finalized' - $ref: '#/components/schemas/WidgetEvent_Heartbeat' - $ref: '#/components/schemas/WidgetEvent_StateChanged' discriminator: propertyName: type mapping: userMessage: '#/components/schemas/WidgetEvent_UserMessage' assistantMessage: '#/components/schemas/WidgetEvent_AssistantMessage' toolApprovalRequested: '#/components/schemas/WidgetEvent_ToolApprovalRequested' toolApproved: '#/components/schemas/WidgetEvent_ToolApproved' toolDenied: '#/components/schemas/WidgetEvent_ToolDenied' toolCalled: '#/components/schemas/WidgetEvent_ToolCalled' toolResult: '#/components/schemas/WidgetEvent_ToolResult' toolError: '#/components/schemas/WidgetEvent_ToolError' error: '#/components/schemas/WidgetEvent_Error' cancelled: '#/components/schemas/WidgetEvent_Cancelled' timedOut: '#/components/schemas/WidgetEvent_TimedOut' finalized: '#/components/schemas/WidgetEvent_Finalized' heartbeat: '#/components/schemas/WidgetEvent_Heartbeat' stateChanged: '#/components/schemas/WidgetEvent_StateChanged' description: >- WidgetEvent is the visitor-facing event vocabulary. It MIRRORS the internal conversation event variants — same granularity, same discriminator names — with slimmed messages holding exactly what a widget UI needs. Internal events map to these through an explicit, exhaustive server-side projection; internal-only types (context compaction, memory reads, sub-agent bookkeeping) have no widget variant and are dropped. Nothing here carries tool configuration, server identities, operator details, or internal error strings. Tool arguments cross this boundary only when an enabled tool set overlay explicitly opts the matching tool in. Page: type: object properties: nextCursor: readOnly: true type: string description: Cursor for the next page. Empty when there are no further results. total: readOnly: true type: integer description: Total number of items matching the request. format: int32 description: |- Page carries pagination data for list responses. A deliberate local duplicate of the api module's Page — this package imports nothing from cadenya.api.v1 (see the workspace README). WidgetSessionErrorInfo: type: object description: >- google.rpc.ErrorInfo detail for widget lifecycle failures. Match both domain and reason; ignore unknown reasons rather than renewing automatically. required: - '@type' - domain - reason properties: '@type': type: string enum: - type.googleapis.com/google.rpc.ErrorInfo domain: type: string enum: - api.cadenya.com reason: $ref: '#/components/schemas/WidgetSessionErrorReason' metadata: type: object additionalProperties: type: string description: Optional non-sensitive context. Never contains tokens or secrets. GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. WidgetEvent_UserMessage: type: object required: - type - userMessage - id - conversationId - createdAt properties: type: type: string enum: - userMessage userMessage: $ref: '#/components/schemas/WidgetUserMessageEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_AssistantMessage: type: object required: - type - assistantMessage - id - conversationId - createdAt properties: type: type: string enum: - assistantMessage assistantMessage: $ref: '#/components/schemas/WidgetAssistantMessageEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolApprovalRequested: type: object required: - type - toolApprovalRequested - id - conversationId - createdAt properties: type: type: string enum: - toolApprovalRequested toolApprovalRequested: $ref: '#/components/schemas/WidgetToolApprovalRequestedEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolApproved: type: object required: - type - toolApproved - id - conversationId - createdAt properties: type: type: string enum: - toolApproved toolApproved: $ref: '#/components/schemas/WidgetToolApprovedEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolDenied: type: object required: - type - toolDenied - id - conversationId - createdAt properties: type: type: string enum: - toolDenied toolDenied: $ref: '#/components/schemas/WidgetToolDeniedEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolCalled: type: object required: - type - toolCalled - id - conversationId - createdAt properties: type: type: string enum: - toolCalled toolCalled: $ref: '#/components/schemas/WidgetToolCalledEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolResult: type: object required: - type - toolResult - id - conversationId - createdAt properties: type: type: string enum: - toolResult toolResult: $ref: '#/components/schemas/WidgetToolResultEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_ToolError: type: object required: - type - toolError - id - conversationId - createdAt properties: type: type: string enum: - toolError toolError: $ref: '#/components/schemas/WidgetToolErrorEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_Error: type: object required: - type - error - id - conversationId - createdAt properties: type: type: string enum: - error error: $ref: '#/components/schemas/WidgetErrorEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_Cancelled: type: object required: - type - cancelled - id - conversationId - createdAt properties: type: type: string enum: - cancelled cancelled: $ref: '#/components/schemas/WidgetCancelledEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_TimedOut: type: object required: - type - timedOut - id - conversationId - createdAt properties: type: type: string enum: - timedOut timedOut: $ref: '#/components/schemas/WidgetTimedOutEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_Finalized: type: object required: - type - finalized - id - conversationId - createdAt properties: type: type: string enum: - finalized finalized: $ref: '#/components/schemas/WidgetFinalizedEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_Heartbeat: type: object required: - type - heartbeat - id - conversationId - createdAt properties: type: type: string enum: - heartbeat heartbeat: $ref: '#/components/schemas/WidgetHeartbeatEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetEvent_StateChanged: type: object required: - type - stateChanged - id - conversationId - createdAt properties: type: type: string enum: - stateChanged stateChanged: $ref: '#/components/schemas/WidgetObjectiveStateChangedEvent' id: readOnly: true type: string description: >- Unique event id (prefixed ULID). Only durable objevt_ IDs are emitted as SSE `id:` fields and accepted as Last-Event-ID reconnect cursors. Transient heartbeats carry hb_ IDs in this payload only. conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation this event belongs to. createdAt: readOnly: true type: string format: date-time WidgetSessionErrorReason: type: string description: >- TOKEN_EXPIRED identifies access-token expiry beyond the 60-second clock-skew tolerance. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. SESSION_* reasons are terminal. Never infer renewability from HTTP status alone. enum: - TOKEN_EXPIRED - SESSION_REVOKED - SESSION_EXPIRED - SESSION_EXHAUSTED WidgetUserMessageEvent: required: - content type: object properties: content: type: string description: WidgetUserMessageEvent is a message from the visitor. WidgetAssistantMessageEvent: required: - content type: object properties: content: type: string description: |- WidgetAssistantMessageEvent is a message from the agent. Content may arrive incrementally: later events for the same turn replace earlier partial content. WidgetToolApprovalRequestedEvent: required: - toolCallId - tool type: object properties: toolCallId: readOnly: true type: string description: >- The tool call awaiting a decision; pass it to the approve/deny endpoint. tool: $ref: '#/components/schemas/WidgetToolReference' description: |- WidgetToolApprovalRequestedEvent asks the visitor to approve or deny a tool call before it runs. The tool reference lets the embedding UI render a custom approval experience per tool; the visitor responds via the approve/deny endpoints. WidgetToolApprovedEvent: required: - toolCallId type: object properties: toolCallId: readOnly: true type: string description: WidgetToolApprovedEvent records that the pending tool call was approved. WidgetToolDeniedEvent: required: - toolCallId type: object properties: toolCallId: readOnly: true type: string description: WidgetToolDeniedEvent records that the pending tool call was denied. WidgetToolCalledEvent: required: - toolCallId - tool type: object properties: toolCallId: readOnly: true type: string tool: $ref: '#/components/schemas/WidgetToolReference' arguments: type: object additionalProperties: true description: |- The final arguments sent to the tool, after parameter actions were applied. Present only when an enabled matching tool set overlay opts the tool into exposing arguments in widget sessions. Arguments are omitted by default because they may contain sensitive customer data. description: WidgetToolCalledEvent reports that the agent invoked a tool. WidgetToolResultEvent: required: - toolCallId - tool type: object properties: toolCallId: readOnly: true type: string tool: $ref: '#/components/schemas/WidgetToolReference' content: allOf: - $ref: '#/components/schemas/GoogleProtobufValue' description: >- The tool's result, present only for tools opted in to sharing content with widget sessions (a per-tool setting; default off). Arbitrary JSON the embedding UI may render — chart data, cards, structured results. x-cadenyaapi-any: true description: >- WidgetToolResultEvent reports that a tool call finished. Result content is omitted by default and included only for tools the workspace has opted in to sharing content with widget sessions. WidgetToolErrorEvent: required: - toolCallId - tool type: object properties: toolCallId: readOnly: true type: string tool: $ref: '#/components/schemas/WidgetToolReference' description: |- WidgetToolErrorEvent reports that a tool call failed. Internal error detail never reaches the widget. WidgetErrorEvent: required: - message type: object properties: message: type: string description: >- WidgetErrorEvent reports a visitor-safe conversation error. The message is sanitized; internal error detail never reaches the widget. WidgetCancelledEvent: type: object properties: {} description: 'WidgetCancelledEvent: the conversation was cancelled. Terminal.' WidgetTimedOutEvent: type: object properties: {} description: >- WidgetTimedOutEvent: the conversation timed out after inactivity. Terminal. WidgetFinalizedEvent: type: object properties: output: type: object description: |- The structured output the agent produced, matching the shape of the agent's output definition schema. description: |- WidgetFinalizedEvent: the conversation's agent produced its structured output and the objective reached its terminal state. Only agents with an output definition finalize — such an agent ends the conversation after one turn, so a widget bound to one should treat this as the answer, not a message to keep chatting past. WidgetHeartbeatEvent: type: object properties: {} description: >- WidgetHeartbeatEvent mirrors objective heartbeat liveness. It is live-only, absent from history, and never a reconnect checkpoint or state transition. WidgetObjectiveStateChangedEvent: required: - fromState - toState type: object properties: fromState: enum: - WIDGET_OBJECTIVE_STATE_UNSPECIFIED - WIDGET_OBJECTIVE_STATE_PENDING - WIDGET_OBJECTIVE_STATE_RUNNING - WIDGET_OBJECTIVE_STATE_WAITING - WIDGET_OBJECTIVE_STATE_FAILED - WIDGET_OBJECTIVE_STATE_CANCELLED - WIDGET_OBJECTIVE_STATE_FINALIZED - WIDGET_OBJECTIVE_STATE_TIMED_OUT type: string format: enum toState: enum: - WIDGET_OBJECTIVE_STATE_UNSPECIFIED - WIDGET_OBJECTIVE_STATE_PENDING - WIDGET_OBJECTIVE_STATE_RUNNING - WIDGET_OBJECTIVE_STATE_WAITING - WIDGET_OBJECTIVE_STATE_FAILED - WIDGET_OBJECTIVE_STATE_CANCELLED - WIDGET_OBJECTIVE_STATE_FINALIZED - WIDGET_OBJECTIVE_STATE_TIMED_OUT type: string format: enum description: |- WidgetObjectiveStateChangedEvent mirrors a durable objective transition. Internal status messages are intentionally omitted. Pending/running maps to a responding conversation, waiting to open, and terminal states to closed. WidgetToolReference: required: - id - name type: object properties: id: readOnly: true example: tool_01HXKD2E5NQM3T9AYWCFMGWT9Y type: string description: Cadenya's canonical tool id. externalId: readOnly: true example: fetch-order-details type: string description: The tool's external id in the customer's namespace, when set. name: readOnly: true type: string description: >- The tool's name as the workspace configured it (e.g. "FetchOrderDetails"). description: >- WidgetToolReference identifies the tool involved in a tool event — enough for the embedding UI to label the activity and to register custom renderers keyed by the tool's id or the customer's own external id. Deliberately omitted: tool configuration, adapter details, and any server identity. GoogleProtobufValue: description: >- Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.