POST /capture-session

Registers a conversation (session) in Hone. Send this once when a conversation begins, then reference the same session_id on every event you capture for it.

POST https://api.hone.dev/api/v1/capture-session

Headers

Header	Value	Required
`x-api-key`	Your API key, `sk_...`	Yes
`Content-Type`	`application/json`	Yes

Body

Field	Type	Required	Description
`session_id`	UUID	Yes	Identifier for this conversation. Reuse it on every event in the conversation.
`user_data`	object	Yes	Details about the end user. Must contain `user_id`. Additional traits are allowed (keep them pseudonymous).
`metadata`	object	No	Free-form session-level metadata. Allowlist the keys you send.
`timestamp`	integer (ms)	No	Epoch milliseconds for when the session started. Defaults to server time.
`client_config`	string	No	A label for the client or SDK that produced the session.

user_data

user_data must include a user_id. Any further keys are stored as traits on the user profile and become filterable dimensions in the dashboard.

Field	Type	Required	Description
`user_id`	string	Yes	Pseudonymous end-user identifier.
…traits	any	No	Extra attributes such as `plan` or `region`.

Request

curl https://api.hone.dev/api/v1/capture-session \
  -H "x-api-key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
    "user_data": {
      "user_id": "user_8f21",
      "plan": "enterprise",
      "region": "eu-west"
    },
    "metadata": {
      "source": "web-widget"
    },
    "client_config": "support-bot/1.4.0"
  }'

Response

{
  "status": "ok",
  "session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33"
}

Generate session_id on your side as a UUID so you can attach it to the events you send next. See POST /capture-event.

​Headers

​Body

​user_data

​Request

​Response

Headers

Body

user_data

Request

Response