Sessions API

The Sessions API is primarily used internally by the SDKs to manage session lifecycle, but can be invoked manually to start, update, or end sessions.

Start a Session

Registers a new session for the given user.

Endpoint

POST /public/sessions/start

Parameters

Parameter	Type	Required	Description
apiKey	string	Yes	Your Public API Key.
distinct_id	string	Yes	The unique identifier of the user.
session_id	string	Yes	A unique string (usually a UUID) for this session.
properties	object	No	Metadata about the session (e.g., OS, browser).

Request Example

curl -X POST "https://api.empmix.com/public/sessions/start" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_PUBLIC_API_KEY",
    "distinct_id": "user_123",
    "session_id": "sess_abc123",
    "properties": {
      "os": "macOS",
      "browser": "Chrome"
    }
  }'

Update a Session

Extends the duration of an active session. Should be called periodically via a heartbeat or ping.

Endpoint

POST /public/sessions/update

Parameters

Parameter	Type	Required	Description
apiKey	string	Yes	Your Public API Key.
distinct_id	string	Yes	The unique identifier of the user.
session_id	string	Yes	The ID of the session to update.
properties	object	No	Optional metadata, often containing 'duration'.

Request Example

{
  "apiKey": "YOUR_PUBLIC_API_KEY",
  "distinct_id": "user_123",
  "session_id": "sess_abc123",
  "properties": {
    "duration": 120
  }
}

End a Session

Marks a session as completed.

Endpoint

POST /public/sessions/end

Parameters

Parameter	Type	Required	Description
apiKey	string	Yes	Your Public API Key.
distinct_id	string	Yes	The unique identifier of the user.
session_id	string	Yes	The ID of the session to end.

Request Example

{
  "apiKey": "YOUR_PUBLIC_API_KEY",
  "distinct_id": "user_123",
  "session_id": "sess_abc123"
}