Sessions

Sessions group related instances under a single named entity. Use them to represent a user journey, a campaign run, or a multi-phase workflow where you need to track, pause, or cancel all instances as a unit.

Create a session

POST /sessions
{
  "tenant_id": "acme",
  "session_key": "onboarding:user-12345",
  "metadata": { "user_id": "12345", "plan": "pro" },
  "expires_at": "2025-02-01T00:00:00Z"
}

// Response
{ "id": "<session-uuid>", "state": "active" }

Attach instances to a session

POST /instances
{
  "sequence_id": "<uuid>",
  "session_id": "<session-uuid>",
  "context": { "data": { "email": "john@acme.com" } }
}

Session operations

• GET /sessions/{id}Get session state and metadata
• GET /sessions/by-key/{tenant_id}/{key}Look up a session by its unique key
• GET /sessions/{id}/instancesList all instances in the session
• PATCH /sessions/{id}/dataUpdate session data
• PATCH /sessions/{id}/stateUpdate session state

Session lifecycle

Sessions transition through three states:

• ActiveAccepting new instances
• CompletedAll instances finished; or explicitly closed
• Expiredexpires_at passed — no new instances accepted; existing complete normally