Public API — Remote Commands & Troubleshooting

How to drive charging stations remotely — reset, start/stop sessions, availability, unlock, diagnostics, firmware — and how to find out why a command didn't do what you expected.

All command endpoints require permission charging-station:remote-control (see Authentication).

v1 vs v2

Both versions expose the same commands with the same request bodies:

• v1 — /api/v1/commands/*. Most endpoints return 204 No Content.
• v2 — /api/v2/commands/*. Every endpoint returns 200 with a JSON body containing ocppMessageId — the correlation ID stamped on the outgoing OCPP message. Store it; it is your handle for tracing the command through OCPP logs (CPMS → OCPP adapter → charging station).

New integrations should use v2. Without ocppMessageId you cannot correlate a command with its OCPP exchange later.

The execution model: accepted ≠ executed

A command request is asynchronous: a 2xx response means the command was validated and dispatched towards the station — not that the station received or executed it. The station's reaction (or silence) arrives later over OCPP and shows up as entity state changes, sessions, webhooks, and OCPP log entries.

Two commands give you more than dispatch:

• unlock-connector waits for the station's reply and returns the actual unlock status.
• start-session returns a command id you can poll for the outcome.

sequenceDiagram
    participant C as Your backend
    participant API as Public API
    participant CS as Charging Station

    C->>API: POST /v2/commands/<command>
    API-->>C: 200 { ocppMessageId }
    Note over API,CS: asynchronous from here
    API->>CS: OCPP call (ocppMessageId)
    CS-->>API: Accepted / Rejected — visible in OCPP logs,<br/>entity state, sessions, webhooks

Command catalog

All paths relative to /api/v1/commands or /api/v2/commands. All are POST unless noted.

Command notes

Reset

SOFT asks the station to restart gracefully (finish transactions first); HARD reboots. Each reset is recorded in the station's restart log together with the API key that requested it.

curl -s -X POST -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "chargingStationId": "EWEL00629", "type": "SOFT" }' \
  "https://<host>/api/v2/commands/reset"

Start / stop session

Covered in depth — with sequence diagrams — in Session Flows. The short version:

• start-session creates a trackable command. Poll GET /v2/commands/start-session/{id}; status moves through PENDING → ACCEPTED → SESSION_CREATED (with sessionId set), or ends in REJECTED / TIMED_OUT.
• stop-session identifies the session by chargingSessionId, or by chargingStationId + ocppTransactionId. The stop is confirmed asynchronously by the station — verify via session status or a webhook.

Change availability

INOPERATIVE takes the target out of service (station screen typically shows "unavailable"); OPERATIVE returns it to service. Three granularities: whole station, one charging point (EVSE), one connector.

OCPP 1.6 caveat: point-level availability requires the point to have exactly one connector (the 1.6 protocol addresses connectors, not EVSEs); otherwise the request is rejected with 400.

Unlock connector

The only fully synchronous command — the response carries the station's verdict:

Trigger message

Asks the station to proactively send a message — the primary self-service diagnostic tool. requestedMessage values (OCPP-standard):

BootNotification, Heartbeat, MeterValues, StatusNotification, DiagnosticsStatusNotification, FirmwareStatusNotification — plus, on stations supporting the extended set, LogStatusNotification and SignChargePointCertificate.

Optional chargingPointId / connectorId scope the trigger (both must belong to the given station, else 422). Triggering StatusNotification on a connector is the quickest way to check whether a station is alive and what state it reports.

Get diagnostics

Requests the station to upload a diagnostics archive. If you pass location (an FTP URL you control), the station uploads there. Without it, a CPMS-hosted FTP location is used and the response url is where the file will appear — the hosted download link is valid for 1 hour, and only after the upload completes (watch for DiagnosticsStatusNotification, or trigger it). startTime/stopTime bound the log window.

Update firmware

Provide exactly one of firmwareId (a firmware entity registered via /api/v1/firmware) or locationUrl (direct download URL for the station). retrieveDate defaults to now. Download and installation progress arrives via FirmwareStatusNotification — visible in the OCPP logs.

Troubleshooting

First rule: verify effect, not response

A 2xx proves dispatch, nothing more. Confirm the actual outcome through:

1. Entity state — station/point/connector status: POST /api/v1/charging-stations/rsql-list with { "filter": "status == 'ONLINE'" }, or GET the entity.
2. Sessions — GET /api/v1/sessions/{id} or a SESSION webhook.
3. OCPP logs — POST /api/v1/charging-stations/{id}/ocpp-logs/rsql-list (permission charging-station:read-logs): the raw request/response exchange with the station. Search around the command timestamp and match the v2 ocppMessageId.

Diagnosis flow

flowchart TD
    A[Command returned 2xx<br/>but nothing happened] --> B{Station ONLINE?}
    B -- no --> C[Station offline — command never reached it.<br/>Check connectivity, then retry]
    B -- yes --> D{OCPP logs show the message?<br/>match ocppMessageId}
    D -- no --> E[Not dispatched — check adapter health,<br/>report with X-Correlation-Id]
    D -- yes --> F{Station reply in logs?}
    F -- Rejected / error --> G[Station refused — see reply payload.<br/>Trigger StatusNotification to inspect state]
    F -- none --> H[Station silent — power/network issue.<br/>Trigger Heartbeat; escalate to field service]

Error responses

Common 422 reasons by command:

Frequent symptoms

Reporting an issue

Include: the endpoint and request body (minus the API key), the response, the X-Correlation-Id response header, the v2 ocppMessageId, and the timestamp with timezone. These let operators trace the exact request through CPMS and OCPP adapter logs.

Related

• Session Flows — remote start/stop sequence diagrams, session lifecycle
• Bulk Operations — running these commands across a fleet of stations
• Webhooks — push confirmation of session state changes
• General guide — errors, pagination, correlation headers
• Authentication — keys, roles, permissions