Your First API Call

This walks you from zero to a working API call against the Headless CPMS gateway. Five minutes if you have Docker handy.

What you’ll build

A request that lists every connected charging station and prints a compact JSON view. By the end you’ll know how to authenticate, how to read the response, and where to look next.

Prerequisites

• Docker installed and running, OR Python 3.11+ (for the source install path)
• curl (you almost certainly have this)
• Five minutes

1. Boot the gateway.

   Docker

   docker run -d --name cpms-headless -p 8080:8080 \
     -e CPMS_API_KEY=hcpms_live_demo \
     ghcr.io/pipelet/cpms-headless:latest

   Source

   git clone https://github.com/pipelet/cpms-headless.git
   cd cpms-headless
   pip install -r requirements.txt
   CPMS_API_KEY=hcpms_live_demo python -m headless_cpms

   The gateway listens on http://localhost:8080. Health check first:

   curl -H "X-API-Key: hcpms_live_demo" \
     http://localhost:8080/api/v1/system/health

   You should see {"status": "ok", ...}.

2. List connected stations.

   curl

   curl -H "X-API-Key: hcpms_live_demo" \
     http://localhost:8080/api/v1/stations | python3 -m json.tool

   Python (requests)

   import requests, json
   
   resp = requests.get(
       "http://localhost:8080/api/v1/stations",
       headers={"X-API-Key": "hcpms_live_demo"},
   )
   print(json.dumps(resp.json(), indent=2))

   Python (wallecpms SDK)

   from wallecpms import HeadlessCPMS
   
   cpms = HeadlessCPMS("http://localhost:8080", api_key="hcpms_live_demo")
   for station in cpms.stations.list():
       print(station["station_id"], station.get("status"))

   The first time, the response will likely be an empty list — you have no stations connected yet. That’s fine. The endpoint works; we just need to give it something to do.

3. Connect a virtual station with the simulator.

   In a second terminal, point the Charger Simulator at your gateway:

   docker run -d --name chargersim -p 9310:9310 \
     -e OCPP_BACKEND_URL=ws://host.docker.internal:8080/ocpp \
     ghcr.io/pipelet/ocpp-chargersim:latest

   Wait ~5 seconds, then re-run the stations call from step 2. You should now see one station: SIM-DC-001.

4. Start a charging session.

   curl -X POST http://localhost:8080/api/v1/transactions/start \
     -H "X-API-Key: hcpms_live_demo" \
     -H "Content-Type: application/json" \
     -d '{
       "station_id": "SIM-DC-001",
       "connectorId": 1,
       "idTag": "RFID_DEMO"
     }'

   Response:

   { "status": "Accepted", "transactionId": 42 }

5. Stop it.

   curl -X POST http://localhost:8080/api/v1/transactions/stop-connector \
     -H "X-API-Key: hcpms_live_demo" \
     -H "Content-Type: application/json" \
     -d '{ "station_id": "SIM-DC-001", "connectorId": 1 }'

Don't ship `hcpms_live_demo` to production

The demo key is plain text in this guide. Generate a real one and store it in a secret manager. See Authentication & API Keys.

What just happened

You hit four endpoints from the Headless CPMS API surface:

Step	Endpoint	What it does
1	GET /api/v1/system/health	Service health probe
2	GET /api/v1/stations	List every connected charge point
4	POST /api/v1/transactions/start	Send RemoteStartTransaction over OCPP
5	POST /api/v1/transactions/stop-connector	Send RemoteStopTransaction

Pipelet translated the REST calls into OCPP 1.6 messages and dispatched them to the (simulated) station. In production this is exactly the same flow against real hardware — the gateway is unaware of whether the station is a wallbox, a 350kW DC charger, or a simulator.

Next steps

Authentication & API Keys Generate proper keys, rotate them safely, and learn the auth model.

Browse the full API reference All 43 Headless CPMS operations with parameters and response schemas.

Subscribe to webhook events Get notified when transactions start/stop instead of polling.