v1

latestOpenAPI 3.0.32026-07-26215.9 KB

SDK

Capture session

Start a session. Call once per conversation; reuse session_id on every event.

post/api/v1/capture-session

Headers

x-org-idstring required

Example:<org-id>

Your organization ID (UUID, case-insensitive).

Request body

session_idstring uuid required

Session UUID. Reuse on every event in this conversation.

metadataobject

Free-form session metadata. Prefer allowlisted operational fields; do not send secrets or sensitive personal data.

timestampinteger

Unix time in ms when the session began. Defaults to server time.

client_configstring

Free-form client/SDK label.

Example request

{
  "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
  "user_data": {
    "user_id": "user-anon-002",
    "email": "user@example.com",
    "user_plan": "pro"
  },
  "metadata": {
    "language": "hi-IN"
  },
  "timestamp": 1714867200000,
  "client_config": "client-segment-001"
}

Response

Session created

session_idstring