Skip to main content
POST
/
v1
/
widget
/
sessions
Create widget session
curl --request POST \
  --url https://api.example.com/v1/widget/sessions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "incidentId": "<string>",
  "ttlSeconds": 123
}
'

​
Overview

Roadmap — not yet available. The embeddable widget is a future feature. Endpoints in this section describe the planned contract; they are not yet exposed in production.
Creates a short-lived session token for embedding the CauseFlow AI assistant widget in your own application. The session token scopes the widget to the specified user and tenant, and expires after 8 hours. Required role: admin or member

​
Request headers

​
Authorization
string
required
JWT Bearer token. Format: Bearer <your-jwt>. The CREATE session endpoint itself requires user auth; the returned session token authenticates all subsequent widget calls.

​
Request body

​
userId
string
required
The ID of the user who will interact with the widget. Must be a valid user in your tenant.
​
incidentId
string
Optional incident ID to pre-load the widget with context for a specific incident.
​
ttlSeconds
integer
Session lifetime in seconds. Default: 28800 (8 hours). Maximum: 86400 (24 hours).

​
Response

Returns 201 Created. 
{
  "sessionId": "wsess_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "sessionToken": "wst_live_EXAMPLE_TOKEN_REDACTED",
  "expiresAt": "2024-04-01T22:00:00Z",
  "widgetUrl": "https://widget.causeflow.ai/embed?session=wsess_01HX9VTPQR3KF8MZWBYD5N6JCE"
}
FieldTypeDescription
sessionIdstringUnique session identifier
sessionTokenstringShort-lived token to authenticate the widget. Pass to the frontend widget SDK.
expiresAtstringISO 8601 expiry timestamp
widgetUrlstringEmbeddable URL for iframe integration
The sessionToken grants widget access for the specified user. Do not log it or expose it to other users. Treat it like a short-lived password.

​
Error responses

StatusError codeDescription
400validation_erroruserId missing or invalid
401unauthorizedMissing or invalid JWT
403forbiddenCaller lacks required role
404user_not_founduserId does not exist in this tenant

​
Examples

curl https://api.causeflow.ai/v1/widget/sessions \
  -X POST \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_01HX9VTPQR3KF8MZWBYD5N6JCE",
    "incidentId": "inc_EXAMPLE_01JX"
  }'

Send message

Send a message to the widget session

Widget stream

Stream AI responses via SSE