Capture Session

Call once per conversation. Reuse session_id on every event that follows.

Body

Field	Type	Required	Description
`session_id`	`string` (UUID)	Required	Session UUID. Reuse on every event in this conversation.
`user_data`	`object`	Required	End-user identity. Must contain `user_id`.
`metadata`	`object`	Optional	Free-form session metadata.
`timestamp`	`integer` (ms)	Optional	Unix time in ms when the session began. Defaults to server time.
`client_config`	`string`	Optional	Free-form client/SDK label.

Verify

After creating a session and sending at least one event, open Events in Voxmith and confirm the session_id appears on the event.

Troubleshooting

session_id must be a UUID.
user_data.user_id is required.
Reuse the same session_id for every event in the conversation.

Next steps

Capture an event: add activity to the session you created.
Authentication: review organization routing and API access.
Ingestion errors: troubleshoot rejected requests.

Headers

x-org-idstringrequired

Your organization ID (UUID, case-insensitive).

Request body

session_idstring · uuidrequired

Session UUID. Reuse on every event in this conversation.

user_dataobjectrequired

End-user identity. user_id is required; other traits are supported for analytics. The example shows shape, but production integrations should prefer a stable pseudonymous ID and avoid raw email, name, phone, or other personal data unless explicitly approved.

user_idstringrequired

metadataobject

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

timestampinteger · int64

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

client_configstring

Free-form client/SDK label.

Responses

200Session created

400Invalid request body