Introduction

Copy linkSession lifecycle

Every session progresses through three phases:

UPCOMING ──plug in──▶ ACTIVE:* ──plug out──▶ SETTLED

The ACTIVE:* sub-state reflects what the system is currently doing, not the overall session type. A session might transition through ACTIVE:BATTERY_RESERVE → ACTIVE:REGULAR as the reserve is filled.

Copy linkManaged vs. unmanaged sessions

Sessions fall into two categories:

Managed sessions (policyId is non-null) are tied to a policy and a location. The system actively controls charging — scheduling blocks, optimizing against energy prices, and tracking progress toward a target. Managed sessions go through the full lifecycle (UPCOMING → ACTIVE:* → SETTLED).

Unmanaged sessions (policyId is null) represent charging that the system observed but did not control. This includes a vehicle charging away from home (e.g. at a public charger), or a vehicle at a location that doesn't have a policy. Unmanaged sessions are always SETTLED — there is no UPCOMING or ACTIVE state because the system isn't managing the charge. They have statistics (energy delivered, battery levels, timeseries) but no blocks, no target, and no outcome.

Get Active Session is scoped to a policy and always returns a managed session. If the vehicle is away from home charging at a public charger, the policy's current session remains UPCOMING — it's still waiting for the vehicle to arrive at the policy's location. Get Settled Session and List Settled Sessions return both managed and unmanaged sessions. In List Settled Sessions, when filtering by vehicleId or locationId, each real-world charging event appears once — the managed session is returned if one exists, otherwise the unmanaged session. Filter by policyId to see only managed sessions.

See Example 7 for what an unmanaged session looks like.

Copy linkEndpoints

Copy linkGet Active Session

Get the current active or upcoming session for a policy. The response provides real-time visibility into what the system is charging towards (target), whether it will succeed (outcome), the actual charge windows (blocks), and energy delivery data (statistics).

GET /flex/vehicle-policies/{policyId}/session

GET /flex/vehicle-policies/f47ac10b-58cc-4372-a567-0e02b2c3d479/session

Copy linkGet Settled Session

Retrieve a single settled session by its ID. Returns both managed and unmanaged sessions.

GET /flex/vehicle-policies/{policyId}/sessions/{sessionId}

GET /flex/vehicle-policies/f47ac10b-58cc-4372-a567-0e02b2c3d479/sessions/c3d4e5f6-a7b8-4012-9def-012345678902

Copy linkList Settled Sessions

Retrieve a paginated list of settled sessions, optionally filtered.

GET /flex/vehicle-policies/sessions

GET /flex/vehicle-policies/sessions?policyId=f47ac10b-58cc-4372-a567-0e02b2c3d479&from=2025-06-01T00:00:00Z&to=2025-06-30T23:59:59Z

{
  "data": [
    { "id": "c3d4e5f6-...", "state": "SETTLED", "..." : "..." },
    { "id": "a8b9c0d1-...", "state": "SETTLED", "..." : "..." }
  ],
  "pagination": {
    "after": "cursor_abc123",
    "before": null
  }
}

Copy linkSet Session Target

Set or replace the target on an active session. A REGULAR target sets a custom charge target and deadline, while an IMMEDIATE_START target forces the vehicle to start charging immediately. Setting a target replaces any existing override. An IMMEDIATE_START target cancels any active restriction.

PUT /flex/sessions/{sessionId}/target

PUT /flex/sessions/f2a3b4c5-d6e7-4890-bcde-f01234567890/target
Content-Type: application/json

{
  "type": "REGULAR",
  "minimumChargeTarget": 90,
  "readyBy": "2025-06-11T08:00:00Z"
}

Copy linkCreate Session Restriction

Create a restriction on an active or upcoming session to request an immediate charging pause. Normal scheduling resumes when the restriction ends or is removed. Charging may continue if the stop command fails or is delayed. A new restriction replaces an existing one and cancels any immediate-start override.

POST /flex/sessions/{sessionId}/restriction

POST /flex/sessions/f2a3b4c5-d6e7-4890-bcde-f01234567890/restriction
Content-Type: application/json

{
  "type": "FULL",
  "endsAt": "2025-06-11T20:00:00Z"
}

The endpoint returns the created restriction with its source, startsAt, endsAt, and createdAt fields.

Copy linkDelete Session Restriction

Remove the active restriction so the optimizer resumes normal scheduling.

DELETE /flex/sessions/{sessionId}/restriction

The endpoint returns 204 No Content, or a 404 restriction-not-found problem when no restriction is active.

Copy linkWebhooks

flex:session:updated

Fired whenever a session changes — state transitions, new blocks, updated statistics, target changes, outcome updates, error state changes, and restriction changes all trigger this event. The payload wraps the full Session object.

{
  "event": "flex:session:updated",
  "userId": "...",
  "createdAt": "2025-06-11T02:30:00Z",
  "session": {
    // Full Session object — same shape as the Get Session response
  }
}