API Overview

Pipelet exposes four HTTP/MCP API surfaces. Together they cover 92+ documented operations across the EV charging stack.

At a glance

API	Operations	Auth	Use when
Headless CPMS	43	X-API-Key	You want one REST gateway for stations, sessions, configuration, webhooks, Hubject.
OCPP Server	39	X-API-Key	You need direct OCPP 1.6 control with full protocol fidelity.
MCP Server	30 tools	env-var key	You’re building an AI agent and want to expose Pipelet as a tool catalog.
Charger Simulator	10+	X-API-Key (optional)	You need to test against real OCPP without buying hardware.

Headless CPMS — the friendly entry point

The unified REST gateway. Most integrations start here.

• Stations: GET /api/v1/stations, compact view, liveness, reset, disconnect, change availability, unlock connector.
• Transactions: list active sessions, start, stop, stop-by-connector.
• Configuration: read/write OCPP config keys, manage local auth lists.
• Triggers: request BootNotification, MeterValues, StatusNotification, DataTransfer from a station.
• Firmware: upload firmware, request diagnostics.
• Webhooks: full CRUD over webhook subscriptions, plus POST /webhooks/{id}/test.
• Hubject: remote start/stop, reservations, sync — for OICP roaming.
• System: health, metrics for the gateway, websocket layer, DB pool.

Browse the Headless reference → All 43 operations with parameters and response schemas.

OCPP Server — the lower layer

If Headless doesn’t expose what you need, you can talk to the OCPP server directly. It’s the layer that owns the WebSocket connections to physical chargers.

• All Headless features, plus:
• Hubject / OICP roaming primitives in more detail
• Plug & Charge (ISO 15118) support — certificate provisioning, contract management
• Per-station configuration dump and restore

Browse the OCPP Server reference → All 39 operations with the full OCPP 1.6 control surface.

MCP Server — for AI agents

The Model Context Protocol server is the differentiator. Instead of teaching a model how to make REST calls, you connect an MCP client (Claude Desktop, your CI agent, anything) and the model gets a typed tool catalog.

• 30 tools across 5 areas: station monitoring, billing & sessions, configuration, customers & tokens, load management.
• Pure async Python, runs over stdio or SSE.
• Backed by the same gateway and broker as the REST APIs — no parallel data path.

Why Pipelet is Claude-ready → The 3-minute setup, the tool catalog, what you can build.

Charger Simulator — sandbox & load test

Not a production API, but a developer’s best friend. Spin up virtual OCPP 1.6 / 2.0.1 chargers and point them at your gateway.

• 1 to 10,000 virtual stations.
• Inject errors, simulate faults, change firmware, run mass load tests.
• Server-Sent Events stream of every OCPP message — perfect for debugging.
• Two protocols supported: OCPP 1.6 and OCPP 2.0.1.

Browse the Chargersim reference → The 10 highest-value endpoints, plus the SSE event stream.

Common patterns

Idempotency

All POST /api/v1/transactions/start and …/stop calls are idempotent within a transaction lifecycle. Calling start twice on an already-charging connector returns the same transactionId rather than starting a new session. Calling stop on a stopped session returns Accepted with no side-effect.

Long-running operations

OCPP messages are dispatched synchronously but the station’s response can take seconds (or minutes for firmware updates). The HTTP API returns as soon as the message is queued — use webhooks (or poll) to learn the actual outcome. Don’t tie your UI’s loading spinner to the HTTP response timeout.

Errors

All four APIs use HTTP status codes the conventional way:

Status	Meaning
200 OK	Success — body contains the result.
202 Accepted	OCPP message queued; outcome will arrive via webhook.
400 Bad Request	Malformed JSON, missing parameter, invalid enum.
401 Unauthorized	Missing or invalid X-API-Key.
404 Not Found	Station / transaction / webhook ID doesn’t exist.
409 Conflict	State machine rejection (e.g. starting a session on a faulted connector).
429 Too Many Requests	Rate limit hit — back off.
5xx	Backend failure — retry with exponential backoff.

Error bodies are JSON: { "error": "human-readable message", "code": "MACHINE_CODE" }.