REST API Documentation

Control chargers, manage settings, and stream OCPP logs — all via a simple REST interface with your personal API key.

Key Authentication
REST Chargers
REST Configuration
REST Global Settings
SSE OCPP Logs
REST Load Test

Authentication

All /api/ endpoints require a personal API key. Each user gets a unique key that scopes access to their own chargers.

Passing the API key

Include the key in one of these ways (in order of preference):

# Header (recommended)
curl -H "X-API-Key: YOUR_KEY" https://sim.pipelet.com/api/chargers

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" https://sim.pipelet.com/api/chargers

# Query parameter (for SSE / EventSource)
curl "https://sim.pipelet.com/api/logs/stream?api_key=YOUR_KEY"

On failure, you receive:

HTTP 401
{"error": "Authentication required"}

Chargers

GET /api/chargers

List all chargers with full operational state.

Response example

[
  {
    "chargepoint_id": "SIM-AC-001",
    "charger_type": "AC",
    "mode": "autopilot",
    "status": "Charging",
    "availability": "Operative",
    "current_power_kw": 11.0,
    "energy_delivered_wh": 4520.0,
    "max_power_kw": 22.0,
    "transaction_id": 12345,
    "connected": true,
    "free_charging": false,
    "num_connectors": 1,
    "backend_url": "ws://ocpp.example.com",
    "rfid_tag": "AABBCCDD",
    "auth_mode": "rfid",
    "pnc_emaid": "",
    "pnc_pcid": "",
    "pnc_certificate_hash": "",
    "ocpp_version": "1.6",
    "charger_name": "Wallbox Garage",
    "error_code": "NoError",
    "session_start": "2026-04-09T14:30:00",
    "session_energy_wh": 4520.0,
    "target_energy_wh": 20000.0,
    "session_id_tag": "AABBCCDD",
    "remote_start": false,
    "heartbeat_interval": 300,
    "connector_status": {"1": "Charging"}
  }
]

POST /api/chargers

Create a charger. Plug & Charge chargers are created as OCPP 2.0.1 and receive a generated eMAID if none is supplied.

Parameter	Type	Description
`chargepoint_id`	string required	Unique chargepoint identifier
`charger_type`	string required	`AC` or `DC`
`max_power_kw`	number required	Maximum charging power
`num_connectors`	number optional	1-5, default 1
`ocpp_version`	string optional	`1.6`, `2.0.1` or `2.1`. Plug & Charge forces `2.0.1`.
`auth_mode`	string optional	`rfid` or `plug_and_charge`
`pnc_emaid`	string optional	ISO 15118 eMAID. Generated from the chargepoint ID when omitted.

GET /api/chargers/{chargepoint_id}

Get a single charger's full state. Same fields as the list endpoint above.

POST /api/chargers/{chargepoint_id}/mode

Set charger operating mode.

Parameter	Type	Description
`mode`	string required	`off`, `on`, `autopilot`, or `manual`

Example

curl -X POST -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"mode": "autopilot"}' \
  https://sim.pipelet.com/api/chargers/SIM-AC-001/mode

POST /api/chargers/{chargepoint_id}/start

Start a manual charging session with a target energy amount.

Parameter	Type	Description
`energy_kwh`	number required	Target energy in kWh (e.g. 20)
`rfid_tag`	string optional	RFID tag. In Plug & Charge mode the configured eMAID is used instead.

POST /api/chargers/{chargepoint_id}/stop

Stop the active charging session on this charger.

POST /api/chargers/{chargepoint_id}/free-charging

Enable or disable free charging (skips OCPP Authorize before StartTransaction).

Parameter	Type	Description
`free_charging`	boolean required	`true` or `false`

POST /api/chargers/{chargepoint_id}/error

Simulate a charger error via OCPP StatusNotification.

Parameter	Type	Description
`error_code`	string required	`NoError`, `GroundFailure`, `OverCurrentFailure`, `EVCommunicationError`, `InternalError`, `ConnectorLockFailure`, `HighTemperature`, `UnderVoltage`, `OverVoltage`

POST /api/chargers/{chargepoint_id}/ocpp-version

Switch OCPP protocol version. Charger must be turned off.

Parameter	Type	Description
`ocpp_version`	string required	`1.6`, `2.0.1` or `2.1`

POST /api/chargers/{chargepoint_id}/name

Set a friendly display name for the charger.

Parameter	Type	Description
`charger_name`	string required	Display name (empty string to clear)

POST /api/chargers/{chargepoint_id}/chargepoint-id

Rename a chargepoint. Charger must be turned off.

Parameter	Type	Description
`chargepoint_id`	string required	New chargepoint identifier

Charger Configuration

POST /api/chargers/{chargepoint_id}/rfid

Set a per-charger RFID tag. Empty string reverts to global default.

Parameter	Type	Description
`rfid_tag`	string required	RFID / idTag value

POST /api/chargers/{chargepoint_id}/auth-config

Set RFID or Plug & Charge / ISO 15118 backend-flow authentication. OCPP 2.0.1 sends idToken.type=eMAID; OCPP 1.6 maps the eMAID to idTag.

Parameter	Type	Description
`auth_mode`	string required	`rfid` or `plug_and_charge`
`rfid_tag`	string optional	RFID / idTag fallback
`pnc_emaid`	string optional	ISO 15118 eMAID. If empty in Plug & Charge mode, a simulator eMAID is generated.
`pnc_pcid`	string optional	Optional contract / provisioning certificate identifier for logs
`pnc_certificate_hash`	string optional	Optional certificate hash for logs

POST /api/chargers/{chargepoint_id}/backend-url

Set a per-charger OCPP backend URL. Empty string reverts to global default.

Parameter	Type	Description
`backend_url`	string required	WebSocket URL (e.g. `ws://ocpp.example.com`)

POST /api/chargers/{chargepoint_id}/num-connectors

Set the number of connectors (1-5). Charger must be turned off.

Parameter	Type	Description
`num_connectors`	integer required	1 to 5

Global Settings

GET /api/settings

Get all global settings and the charger list.

Response example

{
  "settings": {
    "ocpp_backend_url": "ws://ocpp.wall-e.one",
    "rfid_card_id": "AABBCCDD",
    "heartbeat_interval": "300",
    "mass_batch_size": "50",
  },
  "chargers": [
    {
      "chargepoint_id": "SIM-AC-001",
      "charger_type": "AC",
      "mode": "off",
      "num_connectors": 1,
      "backend_url": "",
      "rfid_tag": "AABBCCDD",
      "auth_mode": "plug_and_charge",
      "pnc_emaid": "DE*PIP*SIMAC001",
      "pnc_pcid": "",
      "pnc_certificate_hash": ""
    }
  ]
}

POST /api/settings

Update global settings. Only include the keys you want to change.

Parameter	Type	Description
`ocpp_backend_url`	string optional	Default OCPP backend WebSocket URL
`rfid_card_id`	string optional	Default RFID tag for all chargers
`heartbeat_interval`	integer optional	Heartbeat interval in seconds (10-3600)
`mass_batch_size`	integer optional	Mass charger batch size (10-2500)

Example

curl -X POST -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"ocpp_backend_url": "ws://new-backend:8080", "heartbeat_interval": 120}' \
  https://sim.pipelet.com/api/settings

OCPP Logs

GET /api/logs

Fetch historical OCPP message logs.

Parameter	Type	Description
`chargepoint_id`	string optional	Filter by chargepoint ID
`limit`	integer optional	Max entries to return (default: 200)

Response example

[
  {
    "id": 42,
    "chargepoint_id": "SIM-AC-001",
    "direction": "sent",
    "message_type": "BootNotification",
    "payload": {"chargePointVendor": "Pipelet", "chargePointModel": "Sim"},
    "timestamp": "2026-04-09T15:07:41.368000"
  }
]

GET /api/logs/stream

Real-time log stream via Server-Sent Events (SSE). Each event contains one OCPP message as JSON.

Since EventSource cannot set headers, pass the API key as query parameter:

const es = new EventSource('/api/logs/stream?api_key=YOUR_KEY');
es.onmessage = (e) => console.log(JSON.parse(e.data));

Load Test

GET /api/mass-charger/stats

Get current load test statistics (connected, charging, errors, messages).

POST /api/mass-charger/apply

Start or modify a mass charger load test.

Parameter	Type	Description
`target`	integer required	Number of chargers (0-10000)
`mode`	string required	`idle`, `connect`, or `charging`

POST /api/mass-charger/stop

Stop all mass chargers and disconnect them.

GET /api/mass-charger/errors

Get recent errors from the load test (up to 500 entries).

POST /api/mass-charger/errors/clear

Clear the error log and reset the error counter.