> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehone.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /capture-session

> Open a conversation in Hone. Call once per conversation with a session_id you reuse on every event that follows.

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.

```http theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "status": "ok",
  "session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33"
}
```

<Note>
  Generate `session_id` on your side as a UUID so you can attach it to the events you send next. See [POST /capture-event](/api-reference/capture-event).
</Note>