Sessions

Open a session with a publishable key, refresh or revoke it, update the context, and register a push token.

Create a session

POST /v1/sessions
Authorization: Bearer kl_pub_dev_…
X-Kletso-User-Token: <host jwt>        (optional)
Content-Type: application/json

{ "agentId": "agt_01J8ACME00001",
  "visitorId": "anon_7f3a…",            // anonymous visitors; ignored when a user token is present
  "context": { "plan": "free", "currency": "INR" },
  "device": { "platform": "android", "sdk": "kletso_flutter", "version": "0.1.0", "locale": "en-IN" } }

200:

{ "session":  { "id": "ses_…", "token": "kst_…", "expiresAt": "2026-09-28T13:00:00.000Z" },
  "endUser":  { "id": "eu_…", "anonymous": true, "externalId": null },
  "agent":    { "id": "agt_…", "versionId": "agv_…", "name": "Acme Assistant",
                "greeting": "Hi! I'm Acme's assistant…", "allowedComponents": ["text", "card", "acme.productCard"] },
  "theme":    { "primary": "#FF6A2B", "onPrimary": "#FFFFFF", "surface": "#FFFFFF", "background": "#FBF7F0",
                "text": "#1E2A44", "textMuted": "#6B7280", "radius": 16, "fontFamily": "Plus Jakarta Sans",
                "launcher": { "position": "bottomRight", "icon": "chat" }, "agentDisplayName": "Acme Assistant" },
  "allowedUrlHosts": ["acme.com", "cdn.acme.com"],
  "minClient": "0.1.0",
  "realtime": { "url": "wss://api.kletso.ai/v1/realtime" } }

• agentId defaults to the project’s first agent.
• The agent version is the one active in the key’s environment. In development, an unpublished draft is served when nothing is published. In production a missing version is 409 conflict.
• visitorId becomes external id visitor:<id>; with a user token, sub becomes the external id and name, email, plan, locale, tier claims are stored as traits.
• context is merged into the end user’s stored context.

Refresh

POST /v1/sessions/refresh
Authorization: Bearer kst_…            (may be expired up to 24 h)
→ 200 { "session": { "id", "token", "expiresAt" } }

Revoke

DELETE /v1/sessions/current
Authorization: Bearer kst_…
→ 200 { "ok": true }

Context

PUT   /v1/sessions/current/context   { "context": { … } }   // replace
PATCH /v1/sessions/current/context   { "context": { … } }   // shallow merge
→ 200 { "context": { … } }

Writes the session and end-user context and pushes it into the user’s latest open conversation.

Push token

PUT    /v1/sessions/current/push-token   { "platform": "fcm", "token": "…" }   → 200 { "ok": true }
DELETE /v1/sessions/current/push-token                                          → 200 { "ok": true }

Platforms: fcm (delivered), apns, web_push (accepted, delivery planned).