{ "openapi": "3.1.0", "info": { "title": "SimItNow API", "version": "1.29.2", "description": "REST API for the SimItNow OCPP simulator: create charging stations and virtual EVs, drive transactions, simulate faults and network loss, and run a hosted CSMS. v1 is the fully-supported default; v2 is in beta (see the /v2/csms* endpoints, which are v2-only). Every request must carry the API key in the SIMITNOW-API-KEY header. See https://www.simitnow.com/docs for the human-readable reference this spec is generated alongside." }, "servers": [ { "url": "https://api.simitnow.com" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "SIMITNOW-API-KEY" } } }, "paths": { "/v1/cs/probe": { "post": { "operationId": "probeCsms", "summary": "Probe a CSMS", "description": "Attempt one real WebSocket handshake against the URL a station would use, then close. Nothing is created and no BootNotification is sent, so probing leaves no session, registration or log entry on the target CSMS. Always returns HTTP 200 when the probe ran -- the verdict is in the body. Rate limited to 20 probes/minute per API key; the handshake times out after 8 seconds.", "tags": [ "v1", "v2" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csmsUrl": { "type": "string" }, "id": { "type": "string" }, "protocol": { "type": "string", "default": "ocpp1.6", "enum": [ "ocpp1.6", "ocpp2.0.1", "ocpp2.1" ] }, "security": { "type": "object" } }, "required": [ "csmsUrl", "id" ] }, "example": { "csmsUrl": "wss://csms.example.com/ocpp", "id": "CP-001", "protocol": "ocpp1.6" } } } }, "responses": { "200": { "description": "The probe ran; a failed handshake is still a 200.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "code": { "type": "string" }, "cause": { "type": "string" }, "action": { "type": "string" }, "stages": { "type": "object" }, "statusCode": { "type": [ "integer", "null" ] }, "url": { "type": "string" } } }, "example": { "ok": false, "code": "path_not_found", "cause": "The server does not recognise this path", "action": "Check the path in the URL - did you replace the example value?", "stages": { "dns": "ok", "tcp_tls": "ok", "ocpp_ws": "fail" }, "statusCode": 404, "url": "wss://csms.example.com/ocpp/CP-001" } } } }, "400": { "description": "Malformed body, missing csmsUrl/id, a non ws(s):// URL, or an invalid security profile. Nothing is dialled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "csmsUrl is required" } } } }, "429": { "description": "More than 20 probes in a minute for this API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "probe rate limit exceeded (20/min)" } } } }, "503": { "description": "The rate limiter itself could not be consulted; fails closed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "probe temporarily unavailable" } } } } } } }, "/v2/cs/{cb_id}": { "put": { "operationId": "createChargingStationV2", "summary": "Create Charging Station", "description": "Create and connect a new simulated charging station; it immediately sends a BootNotification to the CSMS at the provided URL.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csmsUrl": { "type": "string" }, "protocol": { "type": "string", "enum": [ "ocpp1.6", "ocpp2.0.1", "ocpp2.1" ] }, "power": { "type": "number", "default": 22 }, "efficiency": { "type": "number", "default": 1.0 }, "connectorCount": { "type": "integer", "default": 1 }, "evseCount": { "type": "integer" }, "connectorsPerEvse": { "type": "integer", "default": 1 }, "chargepointType": { "type": "string", "default": "DC", "enum": [ "AC", "DC" ] }, "reconnectWaitTimeInSeconds": { "type": "integer", "default": 5 }, "isStable": { "type": "boolean", "default": true }, "initialMeterValue": { "type": "number", "default": 0 }, "waitTimeBeforeStartStop": { "type": "integer", "default": 5 }, "emulateRemoteStartFailsToStartCharging": { "type": "boolean", "default": false }, "emulateRemoteStartRejected": { "type": "boolean", "default": false }, "useCommaInMeterValues": { "type": "boolean", "default": false }, "sendEmptyMeterValues": { "type": "boolean", "default": false }, "security": { "type": "object" }, "iccid": { "type": "string", "minLength": 1, "maxLength": 20 }, "imsi": { "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "csmsUrl", "protocol" ] }, "example": { "csmsUrl": "ws://your-csms:9000", "protocol": "ocpp1.6" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "CP-001" } } } }, "409": { "description": "Station with this id already active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 exists" } } } }, "400": { "description": "Unsupported protocol, an invalid/conflicting security profile, or an invalid iccid/imsi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Unsupported protocol: xyz" } } } }, "429": { "description": "Chargepoint limit reached, or today's OCPP message allowance is used up (error \"quota_exceeded\"; it resets at 00:00 UTC).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "quota_exceeded", "message_limit": 500, "message_count": 500 } } } } } }, "get": { "operationId": "getChargingStationV2", "summary": "Get Charging Station Info", "description": "Retrieve the current configuration and connector state of a running station, and the iccid and imsi it reports in BootNotification (null when not set).", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "config": {}, "connector": {}, "network": { "connected": true, "queuedMessages": 0 }, "iccid": "8949000000000000001", "imsi": "001010123456789" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } }, "delete": { "operationId": "deleteChargingStationV2", "summary": "Delete Charging Station", "description": "Stop and remove a simulated charging station.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "CP-001" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v2/cs/{cb_id}/transactions": { "post": { "operationId": "startTransactionV2", "summary": "Transaction Start", "description": "Start a charging transaction on a connector. The connector must be in preparing state, which requires an EV to already be connected.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "integer" }, "idTag": { "type": "string" } }, "required": [ "connectorId" ] }, "example": { "connectorId": 1 } } } }, "responses": { "200": { "description": "Started. On OCPP 1.6, a currently-disconnected station returns a negative placeholder transactionId until the CSMS assigns the real one on reconnect.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "transactionId": 1 } } } }, "400": { "description": "EV not yet connected or connector not ready.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Connector not in preparing state" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } }, "503": { "description": "Station is offline and its message queue is full; the transaction was deliberately not started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 is offline and its message queue is full" } } } } } } }, "/v2/cs/{cb_id}/transactions/{transaction_id}": { "delete": { "operationId": "stopTransactionV2", "summary": "Transaction Stop", "description": "Stop an active charging transaction. The transaction id is in the URL path.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" }, { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Transaction id returned by Transaction Start.", "example": 1 } ], "responses": { "200": { "description": "Stopped.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Already stopped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Transaction not found or already stopped" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v2/cs/{cb_id}/fault": { "post": { "operationId": "setFaultV2", "summary": "Error Set", "description": "Put a connector into a faulted state by setting an OCPP error code.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "integer" }, "errorCode": { "type": "string" } }, "required": [ "connectorId", "errorCode" ] }, "example": { "connectorId": 1, "errorCode": "GroundFailure" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid error code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid errorCode: xyz" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v2/cs/{cb_id}/fault/{connector_id}": { "delete": { "operationId": "resetFaultV2", "summary": "Error Reset", "description": "Clear a faulted connector, returning it to normal operation. The connector id is in the URL path.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connector number on the station.", "example": 1 } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Connector not in a faulted state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Connector not in a faulted state" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v2/cs/{cb_id}/security-event": { "post": { "operationId": "securityEventV2", "summary": "Security Event", "description": "Make the station send an OCPP 1.6 SecurityEventNotification. Security events are reported by the station itself, so there is no CSMS command that triggers one.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "techInfo": { "type": "string" } }, "required": [ "type" ] }, "example": { "type": "TamperDetectionActivated", "techInfo": "enclosure sensor 3" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Missing/invalid type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "type is required and must be a non-empty string" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v2/cs/{cb_id}/network/disconnect": { "post": { "operationId": "networkDisconnectV2", "summary": "Network Disconnect", "description": "Drop the WebSocket connection immediately. With a duration the station reconnects once it has passed; without one it stays offline until network/connect is called. The station keeps running while disconnected: meters advance, connector status changes, and transaction messages are queued for delivery in order once the connection returns.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer" } } }, "example": { "duration": 30 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } }, "409": { "description": "Already disconnected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 is already disconnected" } } } } } } }, "/v2/cs/{cb_id}/network/connect": { "post": { "operationId": "networkConnectV2", "summary": "Network Connect", "description": "Trigger an immediate reconnect attempt.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } }, "409": { "description": "Already connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 is already connected" } } } } } } }, "/v2/cs/{cb_id}/network/power-loss": { "post": { "operationId": "powerLossV2", "summary": "Power Loss", "description": "Simulate a power cut: every active transaction is stopped with reason PowerLoss, then the station goes offline indefinitely. Use Network Connect to bring it back.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } }, "409": { "description": "Already disconnected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 is already disconnected" } } } } } } }, "/v2/ev/{ev_id}": { "put": { "operationId": "createElectricVehicleV2", "summary": "Create Electric Vehicle", "description": "Create a new virtual electric vehicle.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batteryCapacity": { "type": "number" }, "initialSoc": { "type": "number", "default": 0 }, "enableAutoDischarge": { "type": "boolean", "default": true }, "idTag": { "type": "string" }, "maxAcPowerKw": { "type": "number", "default": 11 }, "maxDcPowerKw": { "type": "number", "default": 90 } }, "required": [ "batteryCapacity" ] }, "example": { "batteryCapacity": 60 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "EV-01" } } } }, "409": { "description": "Already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 exists" } } } } } }, "get": { "operationId": "getElectricVehicleV2", "summary": "Get Electric Vehicle Info", "description": "Retrieve the current state of a virtual EV, including SOC and connection status. connectedCbId/connectedConnectorId are null when the EV is not connected.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "EV-01", "soc": 42.5, "capacityWh": 60000, "connectedCbId": "CP-001", "connectedConnectorId": 1, "autoDischarge": true, "idTag": "ABC123", "maxAcPowerKw": 11, "maxDcPowerKw": 90 } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "No active EV found with ev_id: EV-01" } } } } } }, "delete": { "operationId": "deleteElectricVehicleV2", "summary": "Delete Electric Vehicle", "description": "Remove a virtual EV. If connected to a station, it is automatically disconnected first.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "EV-01" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 not found" } } } } } } }, "/v2/ev/{ev_id}/connection": { "post": { "operationId": "connectElectricVehicleV2", "summary": "Connect Electric Vehicle", "description": "Plug the EV into a connector on a charging station. The connector transitions to preparing state asynchronously.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cbId": { "type": "string" }, "connectorId": { "type": "integer" } }, "required": [ "cbId", "connectorId" ] }, "example": { "cbId": "CP-001", "connectorId": 1 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "EV or station not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 not found" } } } }, "409": { "description": "Already connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 is already connected" } } } } } }, "delete": { "operationId": "disconnectElectricVehicleV2", "summary": "Disconnect Electric Vehicle", "description": "Unplug the EV from its current connector.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 not found" } } } } } } }, "/v2/ev/{ev_id}/discharge": { "post": { "operationId": "dischargeElectricVehicleV2", "summary": "Discharge Electric Vehicle", "description": "Manually remove energy from the EV's battery, lowering its state of charge.", "tags": [ "v2" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "power": { "type": "number" } }, "required": [ "power" ] }, "example": { "power": 5000 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "EV-01 not found" } } } } } } }, "/v2/csms": { "put": { "operationId": "createCsmsInstance", "summary": "Create CSMS Instance", "description": "Provision your account's own hosted Central System (CSMS) instance that speaks OCPP 1.6, 2.0.1 and 2.1 -- the reverse direction from every /cs endpoint above: a real or simulated chargepoint dials IN to SimItNow's own CSMS. Idempotent. A new instance is public, so a chargepoint can connect to your address right away; call this to get your connection details or to switch modes.", "tags": [ "v2" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public": { "type": "boolean" } } }, "example": { "public": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "csmsId": "AbCdEf0123456789", "wsHost": "csms.simitnow.com", "public": true, "connectionLimit": 20 } } } } } }, "get": { "operationId": "getCsmsInstance", "summary": "Get CSMS Instance Info", "description": "Read your CSMS instance's current mode, its connection limit (your charging station allowance), and how many connections are live against it.", "tags": [ "v2" ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "csmsId": "AbCdEf0123456789", "wsHost": "csms.simitnow.com", "public": true, "connectionLimit": 20, "activeConnections": 2 } } } }, "404": { "description": "Not provisioned yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "No CSMS instance provisioned yet" } } } } } }, "delete": { "operationId": "clearCsmsInstance", "summary": "Clear CSMS Instance", "description": "Remove every chargepoint registered under your CSMS instance. Does not change csmsId, connection host, or public/private mode. While the instance is public, clearing it does not stop chargepoints connecting.", "tags": [ "v2" ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "deleted": 3 } } } } } } }, "/v2/csms/cp/{cb_id}": { "put": { "operationId": "registerChargepoint", "summary": "Register Chargepoint", "description": "Add a chargepoint to your CSMS instance's allow-list. Returns a one-time HTTP Basic Auth password and the full wss:// connection URL -- the password is shown only once and cannot be recovered afterward. Only works in private mode: a new instance is public and registering is rejected (409) while it is, so switch first with PUT /v2/csms and {\"public\": false}. Deliberately v2-only: no v1 equivalent.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" } }, "required": [ "displayName" ] }, "example": { "displayName": "Test Rig 1" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "cbId": "CP-001", "displayName": "Test Rig 1", "password": "s3cr3t-shown-once", "wsUrl": "wss://csms.simitnow.com/ocpp/AbCdEf0123456789/CP-001" } } } }, "400": { "description": "Missing displayName.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "displayName is required" } } } }, "409": { "description": "Already registered, or the instance is in public mode (no allow-list).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Chargepoint CP-001 is already registered for this account" } } } } } }, "delete": { "operationId": "deleteChargepoint", "summary": "Delete Chargepoint", "description": "Remove a chargepoint from the allow-list. Config-only: an already-connected session is not force-disconnected -- it ends the next time that chargepoint reconnects and its credentials no longer resolve. While your instance is public, deleting a chargepoint does not stop it connecting; switch to private to enforce the allow-list.", "tags": [ "v2" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "CP-001" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Chargepoint CP-001 not found" } } } } } } }, "/v1/cs/create/{cb_id}": { "post": { "operationId": "createChargingStationV1", "summary": "Create Charging Station (v1)", "description": "Same parameters as v2, except iccid and imsi, which only v2 takes. This is the endpoint to build against today; v2 is still in beta.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csmsUrl": { "type": "string" }, "protocol": { "type": "string", "enum": [ "ocpp1.6", "ocpp2.0.1", "ocpp2.1" ] }, "power": { "type": "number", "default": 22 }, "efficiency": { "type": "number", "default": 1.0 }, "connectorCount": { "type": "integer", "default": 1 }, "evseCount": { "type": "integer" }, "connectorsPerEvse": { "type": "integer", "default": 1 }, "chargepointType": { "type": "string", "default": "DC", "enum": [ "AC", "DC" ] }, "reconnectWaitTimeInSeconds": { "type": "integer", "default": 5 }, "isStable": { "type": "boolean", "default": true }, "initialMeterValue": { "type": "number", "default": 0 }, "waitTimeBeforeStartStop": { "type": "integer", "default": 5 }, "emulateRemoteStartFailsToStartCharging": { "type": "boolean", "default": false }, "emulateRemoteStartRejected": { "type": "boolean", "default": false }, "useCommaInMeterValues": { "type": "boolean", "default": false }, "sendEmptyMeterValues": { "type": "boolean", "default": false }, "security": { "type": "object" } }, "required": [ "csmsUrl", "protocol" ] }, "example": { "csmsUrl": "ws://your-csms:9000", "protocol": "ocpp1.6" } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "Simulator CP-001 is created" } } } }, "409": { "description": "Already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 exists" } } } } } } }, "/v1/cs/info/{cb_id}": { "get": { "operationId": "getChargingStationV1", "summary": "Get Charging Station Info (v1)", "description": "Retrieve configuration and connector state of a running station.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "config": {}, "connector": {} } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v1/cs/delete/{cb_id}": { "post": { "operationId": "deleteChargingStationV1", "summary": "Delete Charging Station (v1)", "description": "Stop and remove a simulated charging station.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "Simulator CP-001 is deleted" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Simulator CP-001 not found" } } } } } } }, "/v1/cs/transaction/start/{cb_id}": { "post": { "operationId": "startTransactionV1", "summary": "Transaction Start (v1)", "description": "Start a charging transaction on a connector.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "integer" }, "idTag": { "type": "string" } }, "required": [ "connectorId" ] }, "example": { "connectorId": 1 } } } }, "responses": { "200": { "description": "Started.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "True", "transaction_id": 1 } } } }, "400": { "description": "Connector not ready.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Connector not in preparing state" } } } } } } }, "/v1/cs/transaction/stop/{cb_id}": { "post": { "operationId": "stopTransactionV1", "summary": "Transaction Stop (v1)", "description": "Stop an active charging transaction.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "integer" } }, "required": [ "transactionId" ] }, "example": { "transactionId": 1 } } } }, "responses": { "200": { "description": "Stopped.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "True" } } } }, "400": { "description": "Already stopped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Transaction not found or already stopped" } } } } } } }, "/v1/cs/error/set/{cb_id}": { "post": { "operationId": "setFaultV1", "summary": "Error Set (v1)", "description": "Put a connector into a faulted state.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "integer" }, "errorCode": { "type": "string" } }, "required": [ "connectorId", "errorCode" ] }, "example": { "connectorId": 1, "errorCode": "HighTemperature" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }, "/v1/cs/error/reset/{cb_id}": { "post": { "operationId": "resetFaultV1", "summary": "Error Reset (v1)", "description": "Clear a faulted connector.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorId": { "type": "integer" } }, "required": [ "connectorId" ] }, "example": { "connectorId": 1 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }, "/v1/cs/security_event/{cb_id}": { "post": { "operationId": "securityEventV1", "summary": "Security Event (v1)", "description": "Make the station send an OCPP 1.6 SecurityEventNotification.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "techInfo": { "type": "string" } }, "required": [ "type" ] }, "example": { "type": "TamperDetectionActivated", "techInfo": "enclosure sensor 3" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }, "/v1/cs/network/disconnect/{cb_id}": { "post": { "operationId": "networkDisconnectV1", "summary": "Network Disconnect (v1)", "description": "Drop the WebSocket connection.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer" } } }, "example": { "duration": 30 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }, "/v1/cs/network/connect/{cb_id}": { "post": { "operationId": "networkConnectV1", "summary": "Network Connect (v1)", "description": "Trigger an immediate reconnect attempt.", "tags": [ "v1" ], "parameters": [ { "name": "cb_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charging station id (chargebox id).", "example": "CP-001" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }, "/v1/ev/create/{ev_id}": { "post": { "operationId": "createElectricVehicleV1", "summary": "Create Electric Vehicle (v1)", "description": "Same parameters as v2.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batteryCapacity": { "type": "number" }, "initialSoc": { "type": "number", "default": 0 }, "enableAutoDischarge": { "type": "boolean", "default": true }, "idTag": { "type": "string" }, "maxAcPowerKw": { "type": "number", "default": 11 }, "maxDcPowerKw": { "type": "number", "default": 90 } }, "required": [ "batteryCapacity" ] }, "example": { "batteryCapacity": 60 } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "Created EV-01" } } } } } } }, "/v1/ev/info/{ev_id}": { "get": { "operationId": "getElectricVehicleV1", "summary": "Get Electric Vehicle Info (v1)", "description": "Retrieve current state of a virtual EV.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "EV-01", "soc": 42.5, "capacityWh": 60000 } } } } } } }, "/v1/ev/delete/{ev_id}": { "post": { "operationId": "deleteElectricVehicleV1", "summary": "Delete Electric Vehicle (v1)", "description": "Remove a virtual EV.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "Deleted EV-01" } } } } } } }, "/v1/ev/connect/{ev_id}": { "post": { "operationId": "connectElectricVehicleV1", "summary": "Connect Electric Vehicle (v1)", "description": "Plug an EV into a connector.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cbId": { "type": "string" }, "connectorId": { "type": "integer" } }, "required": [ "cbId", "connectorId" ] }, "example": { "cbId": "CP-001", "connectorId": 1 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "EV-01 is connected to CP-001 connector 1" } } } } } } }, "/v1/ev/disconnect/{ev_id}": { "post": { "operationId": "disconnectElectricVehicleV1", "summary": "Disconnect Electric Vehicle (v1)", "description": "Unplug the EV from its current connector.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "result": "EV-01 is disconnected from CP-001 connector 1" } } } } } } }, "/v1/ev/discharge/{ev_id}": { "post": { "operationId": "dischargeElectricVehicleV1", "summary": "Discharge Electric Vehicle (v1)", "description": "Manually remove energy from the EV battery.", "tags": [ "v1" ], "parameters": [ { "name": "ev_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Electric vehicle id.", "example": "EV-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "power": { "type": "number" } }, "required": [ "power" ] }, "example": { "power": 5000 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } } } }