v2 is in beta. The /v2/ paths below are reachable at api.simitnow.com, but the surface is still evolving and is not the fully-supported default yet. Build against for now; these pages describe where v2 is heading.

Authentication

Every request to the SimItNow API must include your API key in the SIMITNOW-API-KEY header. No request body is needed for authentication; it is checked on every call automatically.

Header SIMITNOW-API-KEY: <your-key>

Example

curl -X GET https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Probe a CSMS

POST https://api.simitnow.com/v1/cs/probe

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 your CSMS. Always returns HTTP 200 when the probe ran: the verdict is in the body. Rate limited to 20 probes per minute per API key; the handshake times out after 8 seconds.

Do not include the chargebox id in csmsUrl. SimItNow appends it as the final path segment automatically. Adding it yourself produces a duplicated path segment in the real connection URL, and many CSMSes reject that as a protocol error immediately after the handshake.
Wrong: csmsUrl: "wss://your-csms/ocpp/CP-001" + id "CP-001" → connects to wss://your-csms/ocpp/CP-001/CP-001
Right: csmsUrl: "wss://your-csms/ocpp" + id "CP-001" → connects to wss://your-csms/ocpp/CP-001

Request

FieldTypeRequiredDescription
csmsUrlstringyesBase WebSocket URL of the CSMS (ws:// or wss://). The chargebox id is appended as the final path segment, exactly as it is for a real station; do not include it yourself.
idstringyesChargebox id to probe with. This matters: many CSMSes authenticate or route on the station identity, so probing without the real id can give a different answer than the station will get.
protocolstringno"ocpp1.6" (default) or "ocpp2.0.1". The probe checks the server actually negotiated this subprotocol.
securityobjectnoSame shape as on create (basicAuth, clientCert, skipServerCertVerify). Pass the profile the station will use. Omitting it means the probe connects unauthenticated, and a correctly configured station will come back as credentials_refused.

Response

FieldTypeDescription
okbooleanWhether the handshake succeeded and the OCPP subprotocol was negotiated
codestringMachine-readable diagnosis (see the table below)
causestringPlain-language description of what happened
actionstringSuggested next step
stagesobjectdns, tcp_tls and ocpp_ws, each "ok", "fail" or "skipped", showing how far the attempt got
statusCodeintegerHTTP status the server answered the upgrade with, or null
urlstringThe exact URL that was probed, chargebox id included

The response never contains the CSMS's own response body, only the status code and SimItNow's classification of it.

Response codes

StatusWhen
200 OKThe probe ran. A failed handshake is still a 200; the verdict is in code.
400 Bad RequestMalformed body, missing csmsUrl/id, a URL that is not ws:///wss://, or an invalid security profile. Nothing is dialled.
429 Too Many RequestsMore than 20 probes in a minute for this API key. Body: {"error": "probe rate limit exceeded (20/min)"}.
503 Service UnavailableThe rate limiter itself could not be consulted. Body: {"error": "probe temporarily unavailable"}. The limit is the only containment control on an endpoint that dials an address you choose, so the probe fails closed rather than running unmetered. Retry shortly.

Diagnosis codes

CodeMeaning
okConnected and the OCPP subprotocol was agreed
dns_failureThe domain did not resolve
address_not_reachableThe name resolves to a private, loopback or otherwise non-public address, which SimItNow's servers cannot reach
connection_refusedThe port is closed
no_responseNo answer before the timeout: the server is down, or a firewall is dropping the connection
certificate_untrustedThe TLS certificate could not be verified
tls_failedThe TLS handshake was rejected; the port may not speak TLS
credentials_refusedHTTP 401/403: the server refused this station's identity or credentials
path_not_foundHTTP 404: the server does not recognise this path
csms_busyHTTP 429/503: the CSMS is temporarily refusing new connections
not_websocketThe address answered like an ordinary web resource, not a WebSocket endpoint
protocol_not_supportedThe handshake completed but the server did not agree to the requested OCPP version
invalid_urlThe URL could not be parsed, most often because of a bad port
invalid_security_profileThe security profile is malformed: a missing password, or a certificate that could not be loaded

Example

curl -X POST https://api.simitnow.com/v1/cs/probe   -H "SIMITNOW-API-KEY: $api_key"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://csms.example.com/ocpp","id":"CP-001","protocol":"ocpp1.6"}'
{"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"}

Create Charging Station

PUT https://api.simitnow.com/v2/cs/{cb_id}

Create and connect a new simulated charging station. The station immediately sends a BootNotification to the CSMS at the provided URL. Returns HTTP 201 Created on success.

Add ?probe=1 to check the CSMS is reachable before the station is created. On failure nothing is created and the call returns HTTP 422 with the same diagnosis body as the probe endpoint. It is opt-in on purpose: the probe can take up to 8 seconds, so making it unconditional would turn a bulk create of several hundred stations into hours. Leave the flag off for batch work and pass it when you are wiring up a station by hand.

Do not include the chargebox id in csmsUrl. SimItNow appends it as the final path segment automatically. Adding it yourself produces a duplicated path segment in the real connection URL, and many CSMSes reject that as a protocol error immediately after the handshake.
Wrong: csmsUrl: "wss://your-csms/ocpp/CP-001" + id "CP-001" → connects to wss://your-csms/ocpp/CP-001/CP-001
Right: csmsUrl: "wss://your-csms/ocpp" + id "CP-001" → connects to wss://your-csms/ocpp/CP-001

Request

FieldTypeRequiredDefaultDescription
csmsUrlstringyes—WebSocket URL of the CSMS (ws:// or wss://). The chargebox id is appended automatically; do not include it yourself.
protocolstringyes—"ocpp1.6" or "ocpp2.0.1". OCPP 2.0.1 uses the native EVSE-aware simulator with BootNotification, StatusNotification, Authorization, TransactionEvent, remote start/stop, periodic meter reporting, device model, security, firmware/log, and smart charging profile support. Multi-EVSE stations are supported via evseCount and connectorsPerEvse.
powernumberno22Charging power in kW
efficiencynumberno1.0Charger efficiency (0.0–1.0)
connectorCountintegerno1Number of connectors
evseCountintegernoconnectorCountNumber of EVSEs; defaults to connectorCount if omitted
connectorsPerEvseintegerno1Connectors per EVSE
chargepointTypestringno"DC""AC" or "DC"
reconnectWaitTimeInSecondsintegerno5Reconnect base wait. At creation time a random value is chosen in [this, max(this+5, this×2)] and fixed for the station's lifetime. Each reconnect attempt then waits [base, 2×base]. Repeated failures escalate further: consecutive handshake timeouts apply a multiplier up to 9×, while a CSMS that keeps rejecting the station, whether because it is busy (429/503), because the credentials are refused (401/403), or because the URL does not exist (404), escalates geometrically up to 5 minutes. The station never stops retrying, so it recovers on its own once the CSMS frees up or the config is corrected
isStablebooleannotrueIf false, simulates an unstable connection
initialMeterValuenumberno0Starting energy meter reading in Wh
waitTimeBeforeStartStopintegerno5Seconds the station waits before acknowledging start/stop commands
emulateRemoteStartFailsToStartChargingbooleannofalseIf true, station accepts RemoteStart but never begins charging
emulateRemoteStartRejectedbooleannofalseIf true, station answers Rejected to every remote start request (OCPP 1.6 RemoteStartTransaction, OCPP 2.0.1 RequestStartTransaction) and changes nothing else; use it to exercise your CSMS's rejection handling
useCommaInMeterValuesbooleannofalseUse comma as decimal separator in MeterValues messages
sendEmptyMeterValuesbooleannofalseSend MeterValues messages with no sampled values
securityobjectnonullOutbound WebSocket security profile for the CSMS connection. Supports SP-0, SP-1, SP-2, and SP-3; see Connection Security below.

Response

HTTP 201 Created
{"id": "CP-001"}

Errors

  • 409 {"error": "Simulator CP-001 exists"}: station with this ID already active
  • 400 {"error": "Unsupported protocol: xyz"}: unrecognised protocol value
  • 400 {"error": "basicAuth and clientCert are mutually exclusive"}: choose either SP-1 Basic Auth or SP-3 client certificate, not both
  • 400 {"error": "clientCert requires wss:// (TLS transport)"}: SP-3 requires a TLS WebSocket URL
  • 429 API quota exceeded

Example

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'

Connection Security

The security object controls how the simulated charging station authenticates when it opens the outbound WebSocket to your CSMS. API authentication is separate and always uses the SIMITNOW-API-KEY request header.

ProfileUse WhenCreate Request
SP-0Your CSMS accepts plain WebSocket connections without extra authentication.Use ws:// or wss:// and omit security.
SP-1Your CSMS requires HTTP Basic Auth during the WebSocket handshake.Set security.basicAuth.password. Optional username; if omitted, SimItNow uses the charge point ID.
SP-2Your CSMS requires TLS transport.Use a wss:// CSMS URL. Add skipServerCertVerify only for self-signed development endpoints.
SP-3Your CSMS requires a client certificate for mutual TLS.Use wss:// and set security.clientCert.certificate plus security.clientCert.privateKey as PEM strings.

security.basicAuth and security.clientCert are mutually exclusive. Client certificates require wss://; otherwise the API returns clientCert requires wss:// (TLS transport).

Security Whitepaper Messages

For CSMS testing, SimItNow advertises the OCPP 1.6 Security feature profile and responds to Security Whitepaper messages with deterministic simulator behavior. It accepts or records GetLog, InstallCertificate, CertificateSigned, DeleteCertificate, GetInstalledCertificateIds, and ExtendedTriggerMessage; it can also send SignCertificate, SecurityEventNotification, and LogStatusNotification when triggered. Certificate handling is in-memory and intended for CSMS workflow validation, not real charge point trust-chain enforcement.

SP-0 Plain WebSocket

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'

SP-1 Basic Auth

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6","security":{"basicAuth":{"username":"shared-user","password":"secret"}}}'

SP-2 TLS / WSS

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"skipServerCertVerify":true}}'

SP-3 Client Certificate

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"clientCert":{"certificate":"-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
","privateKey":"-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"}}}'

Get Charging Station Info

GET https://api.simitnow.com/v2/cs/{cb_id}

Retrieve the current configuration and connector state of a running station. No request body.

Response

HTTP 200 OK
{"config": {...}, "connector": {...}, "network": {"connected": true, "queuedMessages": 0}}

The config object contains the creation parameters; connector contains per-connector state (status, error code, active transaction). network.connected is false while the station is disconnected, and network.queuedMessages counts the transaction messages it is holding until the connection returns.

Errors

  • 404 {"error": "Simulator CP-001 not found"}

Example

curl -X GET https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Delete Charging Station

DELETE https://api.simitnow.com/v2/cs/{cb_id}

Stop and remove a simulated charging station. No request body.

Response

HTTP 200 OK
{"id": "CP-001"}

Errors

  • 404 {"error": "Simulator CP-001 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Transaction Start

POST https://api.simitnow.com/v2/cs/{cb_id}/transactions

Start a charging transaction on a connector. The connector must be in preparing state, which requires an EV to already be connected (via ev/{ev_id}/connection). Returns HTTP 400 if the connector is not ready.

Request

FieldTypeRequiredDefaultDescription
connectorIdintegeryes—Connector to start the transaction on
idTagstringno—RFID tag used for authorization

Response

HTTP 200 OK
{"transactionId": 1}

Save transactionId; it is needed to stop the transaction.

On OCPP 1.6 a station that is currently disconnected returns a negative transactionId. The real one is assigned by your CSMS when the queued StartTransaction is delivered on reconnect; the negative value is a local placeholder and stops the transaction just as well in the meantime.

Errors

  • 400 {"error": "Connector not in preparing state"}: EV not yet connected or connector not ready
  • 404 {"error": "Simulator CP-001 not found"}
  • 503 {"error": "Simulator CP-001 is offline and its message queue is full"}: the transaction was deliberately not started, since the station could not keep the message for delivery

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/transactions   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1}'

Transaction Stop

DELETE https://api.simitnow.com/v2/cs/{cb_id}/transactions/{transaction_id}

Stop an active charging transaction.

The transaction ID is passed in the URL path.

Response

HTTP 200 OK
{}

Errors

  • 400 {"error": "Transaction not found or already stopped"}
  • 404 {"error": "Simulator CP-001 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/transactions/1   -H "SIMITNOW-API-KEY: <your-key>"

Error Set

POST https://api.simitnow.com/v2/cs/{cb_id}/fault

Put a connector into a faulted state by setting an OCPP error code.

Request

FieldTypeRequiredDefaultDescription
connectorIdintegeryes—Connector to fault
errorCodestringyes—Any OCPP 1.6 ChargePointErrorCode value: ConnectorLockFailure, EVCommunicationError, GroundFailure, HighTemperature, InternalError, LocalListConflict, NoError, OtherError, OverCurrentFailure, OverVoltage, PowerMeterFailure, PowerSwitchFailure, ReaderFailure, ResetFailure, UnderVoltage, WeakSignal

Response

HTTP 200 OK
{}

Errors

  • 400 {"error": "Invalid errorCode: xyz"}
  • 404 {"error": "Simulator CP-001 not found"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/fault   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1,"errorCode":"GroundFailure"}'

Error Reset

DELETE https://api.simitnow.com/v2/cs/{cb_id}/fault/{connector_id}

Clear a faulted connector, returning it to normal operation.

The connector ID is passed in the URL path.

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "Simulator CP-001 not found"}
  • 400 {"error": "Connector not in a faulted state"}

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/fault/1   -H "SIMITNOW-API-KEY: <your-key>"

Security Event

POST https://api.simitnow.com/v2/cs/{cb_id}/security-event

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; this endpoint is how you exercise your CSMS's handling of them.

Request

FieldTypeRequiredDefaultDescription
typestringyes—Event type, up to 50 characters. Vendor-specific values are allowed. The standard types are FirmwareUpdated, FailedToAuthenticateAtCentralSystem, CentralSystemFailedToAuthenticate, SettingSystemTime, StartupOfTheDevice, ResetOrReboot, SecurityLogWasCleared, ReconfigurationOfSecurityParameters, MemoryExhaustion, InvalidMessages, AttemptedReplayAttacks, TamperDetectionActivated, InvalidFirmwareSignature, InvalidFirmwareSigningCertificate, InvalidCentralSystemCertificate, InvalidChargePointCertificate, InvalidTLSVersion, InvalidTLSCipherSuite, MaintenanceLoginAccepted, MaintenanceLoginFailed, DiscardedRenewedClientCertificate
techInfostringno—Additional detail, up to 255 characters

Response

HTTP 200 OK
{}

Errors

  • 400 {"error": "type is required and must be a non-empty string"}
  • 404 {"error": "Simulator CP-001 not found"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/security-event   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"type":"TamperDetectionActivated","techInfo":"enclosure sensor 3"}'

Network Disconnect

POST https://api.simitnow.com/v2/cs/{cb_id}/network/disconnect

Drop the WebSocket connection immediately. The station will attempt to reconnect automatically.

Optional body: {"duration": 30} (seconds to stay disconnected; 0 = reconnect immediately).

The station keeps running while disconnected: meters advance, connector status changes, and a transaction can still be started for an id tag held in the local authorization list. Transaction messages produced during the outage (StartTransaction, MeterValues, StopTransaction, or TransactionEvent on OCPP 2.0.1) are queued and delivered in order once the connection returns; OCPP 2.0.1 events are marked offline: true. Heartbeats and status notifications are not queued; the station reports its current status once it is back. A transaction started offline on OCPP 1.6 reports a negative placeholder transaction id until the CSMS assigns the real one during replay.

RemoteStartTransaction cannot reach a disconnected station: it travels from the CSMS to the station, so there is no connection for it to arrive on.

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "Simulator CP-001 not found"}
  • 409 {"error": "Simulator CP-001 is already disconnected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/disconnect   -H "SIMITNOW-API-KEY: <your-key>"

Network Connect

POST https://api.simitnow.com/v2/cs/{cb_id}/network/connect

Trigger an immediate reconnect attempt. No request body.

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "Simulator CP-001 not found"}
  • 409 {"error": "Simulator CP-001 is already connected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/connect   -H "SIMITNOW-API-KEY: <your-key>"

Power Loss

POST https://api.simitnow.com/v2/cs/{cb_id}/network/power-loss

Simulate a power cut: every active transaction is stopped with reason PowerLoss, then the station goes offline indefinitely. No request body.

The sessions are stopped before the station goes offline, so your CSMS receives the StopTransaction messages straight away and sees how each session ended. Use POST /v2/cs/{cb_id}/network/connect to bring the station back.

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "Simulator CP-001 not found"}
  • 409 {"error": "Simulator CP-001 is already disconnected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/power-loss   -H "SIMITNOW-API-KEY: <your-key>"

Create Electric Vehicle

PUT https://api.simitnow.com/v2/ev/{ev_id}

Create a new virtual electric vehicle. Returns HTTP 201 Created on success.

Request

FieldTypeRequiredDefaultDescription
batteryCapacitynumberyes—Battery capacity in kWh
initialSocnumberno0Initial state of charge (0–100)
enableAutoDischargebooleannotrueIf true, battery drains gradually when not charging
idTagstringno—RFID tag used for authorization
maxAcPowerKwnumberno11Max AC charging power the EV accepts in kW
maxDcPowerKwnumberno90Max DC charging power the EV accepts in kW

Response

HTTP 201 Created
{"id": "EV-01"}

Errors

  • 409 {"error": "EV-01 exists"}

Example

curl -X PUT https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"batteryCapacity":60}'

Get Electric Vehicle Info

GET https://api.simitnow.com/v2/ev/{ev_id}

Retrieve the current state of a virtual EV, including SOC and connection status. No request body.

Response

HTTP 200 OK
{
  "id": "EV-01",
  "soc": 42.5,
  "capacityWh": 60000,
  "connectedCbId": "CP-001",
  "connectedConnectorId": 1,
  "autoDischarge": true,
  "idTag": "ABC123",
  "maxAcPowerKw": 11,
  "maxDcPowerKw": 90
}

connectedCbId and connectedConnectorId are null when the EV is not connected.

Errors

  • 404 {"error": "No active EV found with ev_id: EV-01"}

Example

curl -X GET https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Delete Electric Vehicle

DELETE https://api.simitnow.com/v2/ev/{ev_id}

Remove a virtual EV. If the EV is connected to a station, it is automatically disconnected first. No request body.

Response

HTTP 200 OK
{"id": "EV-01"}

Errors

  • 404 {"error": "EV-01 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Connect Electric Vehicle

POST https://api.simitnow.com/v2/ev/{ev_id}/connection

Plug the EV into a connector on a charging station. The connector transitions to preparing state asynchronously. Poll GET /v2/cs/{cb_id} and confirm the connector shows preparing before calling transactions.

Request

FieldTypeRequiredDefaultDescription
cbIdstringyes—ID of the charging station to connect to
connectorIdintegeryes—Connector number on that station

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "EV-01 not found"}
  • 404 {"error": "CP-001 not found"}
  • 409 {"error": "EV-01 is already connected"}

Example

curl -X POST https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"cbId":"CP-001","connectorId":1}'

Disconnect Electric Vehicle

DELETE https://api.simitnow.com/v2/ev/{ev_id}/connection

Unplug the EV from its current connector. No request body.

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "EV-01 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"

Discharge Electric Vehicle

POST https://api.simitnow.com/v2/ev/{ev_id}/discharge

Manually remove energy from the EV's battery, lowering its state of charge.

Request

FieldTypeRequiredDefaultDescription
powernumberyes—Energy to remove from the battery in Wh (watt-hours, not kW)

Response

HTTP 200 OK
{}

Errors

  • 404 {"error": "EV-01 not found"}

Example

curl -X POST https://api.simitnow.com/v2/ev/EV-01/discharge   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"power":5000}'

Create CSMS Instance

PUT https://api.simitnow.com/v2/csms

Provision your account's own hosted OCPP 1.6 Central System (CSMS) instance — the reverse direction from everything above: instead of SimItNow simulating a station and dialing out to your CSMS, a real or simulated chargepoint implementation dials in to SimItNow's own CSMS. Idempotent: safe to call more than once, always returns the same csmsId for your account. Most callers never need this endpoint explicitly — registering a chargepoint provisions it automatically on first use. Call it directly if you want your connection details up front, before registering any chargepoint.

Your CSMS instance has two modes:

ModeBehavior
Private (default)Only chargepoints you explicitly register can connect, and each one authenticates with its own HTTP Basic Auth password.
PublicAny chargepoint can connect with no registration and no credentials at all (OCPP Security Profile 0 — plain, unauthenticated WebSocket). There is no allow-list in this mode: registering a chargepoint is rejected while public, since there is nothing to add it to. Concurrent connections are capped per account (see connectionLimit below) to bound how much an open, unauthenticated endpoint can be used for.
Public means literally unauthenticated. Anyone who knows (or guesses) your csmsId can connect a chargepoint identity of their choosing while your instance is public — there is no password, no allow-list, and no way to restrict which cb_id values are accepted. Use public mode for short-lived, disposable testing (a chargepoint vendor validating their own client against a real Central System), and switch back to private ({"public": false}) when you are done. csmsId is a long random token, not a secret designed to resist a targeted guess indefinitely.

Request

FieldTypeRequiredDefaultDescription
publicbooleanno(unchanged)Set the instance's mode. Omit this field entirely to leave the current mode untouched — the common "just fetch my csmsId" call never has the side effect of silently reverting an already-public instance back to private. A brand-new instance defaults to private regardless.

Response

HTTP 200 OK
{"csmsId": "AbCdEf0123456789", "wsHost": "csms.simitnow.com", "public": false, "connectionLimit": 5}

Example

curl -X PUT https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"public":true}'

Get CSMS Instance Info

GET https://api.simitnow.com/v2/csms

Read your CSMS instance's current mode and, in public mode, how many concurrent connections are live against the cap. No request body.

Response

HTTP 200 OK
{
  "csmsId": "AbCdEf0123456789",
  "wsHost": "csms.simitnow.com",
  "public": true,
  "connectionLimit": 5,
  "activeConnections": 2
}

Errors

  • 404 {"error": "No CSMS instance provisioned yet"}

Example

curl -X GET https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"

Clear CSMS Instance

DELETE https://api.simitnow.com/v2/csms

Remove every chargepoint registered under your CSMS instance. This does not change your csmsId, connection host, or public/private mode — a chargepoint you register afterward gets the exact same wss:// host as before. No request body.

Response

HTTP 200 OK
{"deleted": 3}

Example

curl -X DELETE https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"

Register Chargepoint

PUT https://api.simitnow.com/v2/csms/cp/{cb_id}

Add a chargepoint to your CSMS instance so it can connect and authenticate — the allow-list entry for the inbound direction. Returns a one-time HTTP Basic Auth password and the full wss:// connection URL; the password is shown only once here and cannot be recovered afterward (only its salted hash is stored). Provisions your CSMS instance automatically on first call if you haven't already via Create CSMS Instance. Deliberately v2-only: no v1 equivalent, and no GET info route.

Request

FieldTypeRequiredDefaultDescription
displayNamestringyes—Human-readable label shown on the dashboard's “Chargepoints (CSMS)” list

Response

HTTP 201 Created
{
  "cbId": "CP-001",
  "displayName": "Test Rig 1",
  "password": "s3cr3t-shown-once",
  "wsUrl": "wss://csms.simitnow.com/ocpp/AbCdEf0123456789/CP-001"
}

Errors

  • 400 {"error": "displayName is required"}
  • 409 {"error": "Chargepoint CP-001 is already registered for this account"}
  • 409 {"error": "This CSMS instance is public: it has no chargepoint allow-list, ..."} — see Create CSMS Instance; switch back to private first if you need an allow-list entry.

Example

curl -X PUT https://api.simitnow.com/v2/csms/cp/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"displayName":"Test Rig 1"}'

Delete Chargepoint

DELETE https://api.simitnow.com/v2/csms/cp/{cb_id}

Remove a chargepoint from your CSMS instance's allow-list. Config-only: an already-connected session is not force-disconnected by this call — it ends the next time that chargepoint reconnects and its credentials no longer resolve. No request body.

Response

HTTP 200 OK
{"id": "CP-001"}

Errors

  • 404 {"error": "Chargepoint CP-001 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/csms/cp/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Guide: Full Session Lifecycle Beta

A complete walkthrough using CP-001 and EV-01. Each step shows the curl command and expected response.

  1. Create a charging station
    curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'
    {"id": "CP-001"}

    Returns HTTP 201. The station sends BootNotification to your CSMS immediately.

  2. Create a virtual EV
    curl -X PUT https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"batteryCapacity":60}'
    {"id": "EV-01"}

    Returns HTTP 201.

  3. Connect the EV to the station
    curl -X POST https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"cbId":"CP-001","connectorId":1}'
    {}

    The connector transitions to preparing state asynchronously. Poll GET /v2/cs/CP-001 until the connector shows preparing before proceeding.

  4. Start a transaction
    curl -X POST https://api.simitnow.com/v2/cs/CP-001/transactions   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1}'
    {"transactionId": 1}

    Save transactionId. This triggers StartTransaction and begins periodic MeterValues.

  5. Poll EV info to observe charging
    curl -X GET https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
    {"id": "EV-01", "soc": 42.5, "capacityWh": 60000, ...}

    Watch soc rise in real time.

  6. Stop the transaction
    curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/transactions/1   -H "SIMITNOW-API-KEY: <your-key>"
    {}

    The transaction ID is in the URL path; no request body needed. This triggers StopTransaction to the CSMS.

  7. Disconnect the EV
    curl -X DELETE https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"
    {}
  8. Clean up
    curl -X DELETE https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
curl -X DELETE https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"
    {"id": "EV-01"}
{"id": "CP-001"}

Authentication

Every request to the SimItNow API must include your API key in the SIMITNOW-API-KEY header. No request body is needed for authentication; it is checked on every call automatically.

Header SIMITNOW-API-KEY: <your-key>

Example

curl -X GET https://api.simitnow.com/v1/cs/info/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Create Charging Station

POST https://api.simitnow.com/v1/cs/create/{cb_id}

Same parameters as v2. This is the endpoint to build against today; v2 is still in beta.

Add ?probe=1 to check the CSMS is reachable before the station is created. On failure nothing is created and the call returns HTTP 422 with the same diagnosis body as the probe endpoint. It is opt-in on purpose: the probe can take up to 8 seconds, so making it unconditional would turn a bulk create of several hundred stations into hours. Leave the flag off for batch work and pass it when you are wiring up a station by hand.

Do not include the chargebox id in csmsUrl. SimItNow appends it as the final path segment automatically. Adding it yourself produces a duplicated path segment in the real connection URL, and many CSMSes reject that as a protocol error immediately after the handshake.
Wrong: csmsUrl: "wss://your-csms/ocpp/CP-001" + {cb_id} path "CP-001" → connects to wss://your-csms/ocpp/CP-001/CP-001
Right: csmsUrl: "wss://your-csms/ocpp" + {cb_id} path "CP-001" → connects to wss://your-csms/ocpp/CP-001

Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}}'

Connection Security

The v1 create endpoint accepts the same security object as v2. Use it to control the outbound WebSocket connection from the simulated station to your CSMS.

SimItNow also supports OCPP 1.6 Security Whitepaper messages for CSMS testing: GetLog, InstallCertificate, CertificateSigned, DeleteCertificate, GetInstalledCertificateIds, ExtendedTriggerMessage, SignCertificate, SecurityEventNotification, and LogStatusNotification.

ProfileCreate Request
SP-0Omit security for plain WebSocket.
SP-1Use security.basicAuth for Basic Auth. If username is omitted, SimItNow uses the charge point ID.
SP-2Use a wss:// CSMS URL for TLS; skipServerCertVerify is available for self-signed development endpoints.
SP-3Use security.clientCert with PEM certificate and privateKey. SP-3 requires wss://.

SP-1 Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6","security":{"basicAuth":{"password":"secret"}}}'

SP-3 Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"clientCert":{"certificate":"-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
","privateKey":"-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"}}}'

Get Charging Station Info

GET https://api.simitnow.com/v1/cs/info/{cb_id}

Retrieve configuration and connector state of a running station. Use GET /v2/cs/{cb_id} for new integrations.

Example

curl -X GET https://api.simitnow.com/v1/cs/info/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Delete Charging Station

POST https://api.simitnow.com/v1/cs/delete/{cb_id}

Stop and remove a simulated charging station. Use DELETE /v2/cs/{cb_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/cs/delete/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Transaction Start

POST https://api.simitnow.com/v1/cs/transaction/start/{cb_id}

Start a charging transaction. Body: connectorId (required), idTag (optional).

Example

curl -X POST https://api.simitnow.com/v1/cs/transaction/start/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'

Transaction Stop

POST https://api.simitnow.com/v1/cs/transaction/stop/{cb_id}

Stop an active charging transaction. Body: transactionId.

Example

curl -X POST https://api.simitnow.com/v1/cs/transaction/stop/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"transactionId":1}}'

Error Set

POST https://api.simitnow.com/v1/cs/error/set/{cb_id}

Put a connector into a faulted state. Body: connectorId, errorCode.

Example

curl -X POST https://api.simitnow.com/v1/cs/error/set/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1,"errorCode":"HighTemperature"}}'

Error Reset

POST https://api.simitnow.com/v1/cs/error/reset/{cb_id}

Clear a faulted connector. Body: connectorId.

Example

curl -X POST https://api.simitnow.com/v1/cs/error/reset/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'

Security Event

POST https://api.simitnow.com/v1/cs/security_event/{cb_id}

Make the station send an OCPP 1.6 SecurityEventNotification. Body: type (required, up to 50 characters), techInfo (optional, up to 255).

Example

curl -X POST https://api.simitnow.com/v1/cs/security_event/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"type":"TamperDetectionActivated","techInfo":"enclosure sensor 3"}}'

Network Disconnect

POST https://api.simitnow.com/v1/cs/network/disconnect/{cb_id}

Drop the WebSocket connection. Optional body: duration (seconds to stay disconnected).

Example

curl -X POST https://api.simitnow.com/v1/cs/network/disconnect/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Network Connect

POST https://api.simitnow.com/v1/cs/network/connect/{cb_id}

Trigger an immediate reconnect attempt. No request body.

Example

curl -X POST https://api.simitnow.com/v1/cs/network/connect/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Create Electric Vehicle

POST https://api.simitnow.com/v1/ev/create/{ev_id}

Same parameters as v2. Use POST /v2/ev/{ev_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/ev/create/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"batteryCapacity":60}}'

Get Electric Vehicle Info

GET https://api.simitnow.com/v1/ev/info/{ev_id}

Retrieve current state of a virtual EV. Use GET /v2/ev/{ev_id} for new integrations.

Example

curl -X GET https://api.simitnow.com/v1/ev/info/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Delete Electric Vehicle

POST https://api.simitnow.com/v1/ev/delete/{ev_id}

Remove a virtual EV. Use DELETE /v2/ev/{ev_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/ev/delete/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Connect Electric Vehicle

POST https://api.simitnow.com/v1/ev/connect/{ev_id}

Plug an EV into a connector. Body: cbId, connectorId.

Example

curl -X POST https://api.simitnow.com/v1/ev/connect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"cbId":"CP-001","connectorId":1}}'

Disconnect Electric Vehicle

POST https://api.simitnow.com/v1/ev/disconnect/{ev_id}

Unplug the EV from its current connector. No request body.

Example

curl -X POST https://api.simitnow.com/v1/ev/disconnect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Discharge Electric Vehicle

POST https://api.simitnow.com/v1/ev/discharge/{ev_id}

Manually remove energy from the EV battery. Body: power (Wh to remove).

Example

curl -X POST https://api.simitnow.com/v1/ev/discharge/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"power":5000}}'

Guide: Full Session Lifecycle

A complete walkthrough using CP-001 and EV-01 with v1 endpoints.

  1. Create a charging station
    curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}}'
    {"result": "Simulator CP-001 is created"}
  2. Create a virtual EV
    curl -X POST https://api.simitnow.com/v1/ev/create/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"batteryCapacity":60}}'
    {"result": "Created EV-01"}
  3. Connect the EV to the station
    curl -X POST https://api.simitnow.com/v1/ev/connect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"cbId":"CP-001","connectorId":1}}'
    {"result": "EV-01 is connected to CP-001 connector 1"}

    Poll GET /v1/cs/info/CP-001 until the connector shows preparing.

  4. Start a transaction
    curl -X POST https://api.simitnow.com/v1/cs/transaction/start/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'
    {"result": "True", "transaction_id": 1}
  5. Poll EV info to observe charging
    curl -X GET https://api.simitnow.com/v1/ev/info/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
    {"id": "EV-01", "soc": 42.5, "capacityWh": 60000, ...}
  6. Stop the transaction
    curl -X POST https://api.simitnow.com/v1/cs/transaction/stop/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"transactionId":1}}'
    {"result": "True"}
  7. Disconnect the EV
    curl -X POST https://api.simitnow.com/v1/ev/disconnect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
    {"result": "EV-01 is disconnected from CP-001 connector 1"}
  8. Clean up
    curl -X POST https://api.simitnow.com/v1/ev/delete/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
curl -X POST https://api.simitnow.com/v1/cs/delete/CP-001   -H "SIMITNOW-API-KEY: <your-key>"
    {"result": "Deleted EV-01"}
{"result": "Simulator CP-001 is deleted"}