CPO Commands — Control Chargers as an Operator

Send commands to one or many charge points as a CPO. Includes single-charger commands, bulk operations, and command history for audit trails.

CPO command endpoints let Charge Point Operators send operational commands to their charge point fleet. Unlike the OCPP 1.6 endpoints that map directly to OCPP protocol actions, CPO commands are higher-level operations that Dynamo CSMS translates to the appropriate OCPP messages automatically.

All CPO command endpoints require an organization API key with the write:charge_points scope. History endpoints additionally require read:charge_points.

Base URL: https://api.dynamo-csms.com

---

Send command to a charge point

POST /api/v1/cpo/commands/{charge_point_id}

Sends a command to a single charge point. The command is executed immediately and the response includes the charge point’s acknowledgement.

charge_point_id · string · required

The unique identifier of the target charge point.

command · string · required

The command to execute. See the supported commands table below for valid values.

parameters · object

Command-specific parameters. Required fields vary by command — see the command reference below.

timeout_seconds · integer

How long to wait for the charge point to acknowledge the command (default: 10, max: 60).

Supported commands

Command	Description	Required parameters
start_session	Start a charging session	connector_id, id_tag
stop_session	Stop an active session	transaction_id
set_available	Mark connector as available	connector_id
set_unavailable	Mark connector as unavailable	connector_id
soft_reset	Restart after active sessions end	—
hard_reset	Immediate restart	—
set_power_limit	Cap charging power	connector_id, limit_watts
clear_power_limit	Remove power cap	connector_id
unlock_connector	Mechanically unlock connector	connector_id
update_firmware	Trigger firmware update	firmware_url, retrieve_date
get_diagnostics	Request diagnostic upload	upload_url
send_local_list	Push local RFID authorization list	list_version, local_authorization_list

cURL — start session

curl -X POST https://api.dynamo-csms.com/api/v1/cpo/commands/CP-SITE42-001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "start_session",
    "parameters": {
      "connector_id": 1,
      "id_tag": "RFID-USER-4A2F"
    }
  }'

Response 200 OK

{
  "command_id": "cmd_8b3f1a9c",
  "charge_point_id": "CP-SITE42-001",
  "command": "start_session",
  "status": "Accepted",
  "parameters": {
    "connector_id": 1,
    "id_tag": "RFID-USER-4A2F"
  },
  "charge_point_response": {
    "status": "Accepted"
  },
  "executed_at": "2024-03-10T15:45:00Z",
  "response_time_ms": 185
}

command_id · string

Unique identifier for this command execution. Use it to look up history.

status · string

Dynamo CSMS status: Accepted, Rejected, Timeout, Error.

charge_point_response · object

Raw OCPP response from the charge point.

response_time_ms · integer

Milliseconds between sending the command and receiving the charge point acknowledgement.

---

Send bulk command

POST /api/v1/cpo/commands/bulk

Sends the same command to multiple charge points simultaneously. Commands are dispatched in parallel. The response includes per-charge-point results.

charge_point_ids · string[] · required

List of charge point identifiers to target. Maximum 100 per request.

command · string · required

The command to send to all charge points. Must be the same command for all targets.

parameters · object

Parameters applied uniformly to all charge points.

timeout_seconds · integer

Per-charge-point timeout in seconds (default: 10, max: 60).

continue_on_failure · boolean

If true, continues sending to remaining charge points even if some fail. Defaults to true.

curl -X POST https://api.dynamo-csms.com/api/v1/cpo/commands/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_point_ids": [
      "CP-SITE42-001",
      "CP-SITE42-002",
      "CP-SITE42-003"
    ],
    "command": "soft_reset",
    "continue_on_failure": true
  }'

Response 207 Multi-Status

{
  "bulk_command_id": "bulk_2c7a4f9e",
  "command": "soft_reset",
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {
      "charge_point_id": "CP-SITE42-001",
      "command_id": "cmd_9a1b3c5d",
      "status": "Accepted",
      "response_time_ms": 142
    },
    {
      "charge_point_id": "CP-SITE42-002",
      "command_id": "cmd_9a1b3c5e",
      "status": "Accepted",
      "response_time_ms": 167
    },
    {
      "charge_point_id": "CP-SITE42-003",
      "command_id": "cmd_9a1b3c5f",
      "status": "Timeout",
      "error": "Charge point did not respond within 10 seconds",
      "response_time_ms": null
    }
  ],
  "executed_at": "2024-03-10T16:00:00Z"
}

bulk_command_id · string

Identifier for the bulk operation as a whole.

succeeded · integer

Number of charge points that returned Accepted.

failed · integer

Number of charge points that timed out, rejected, or errored.

results · array

Per-charge-point result objects.

results[].status · string

Per-charge-point outcome: Accepted, Rejected, Timeout, Error, Offline.

---

Get command history for a charge point

GET /api/v1/cpo/commands/{charge_point_id}/history

Returns the history of commands sent to a specific charge point, ordered by most recent first.

charge_point_id · string · required

The charge point to retrieve history for.

command · string

Filter by command type (e.g. start_session, soft_reset).

status · string

Filter by outcome: Accepted, Rejected, Timeout, Error.

from · string

ISO 8601 start of date range (e.g. "2024-03-01T00:00:00Z").

to · string

ISO 8601 end of date range.

page · integer

Page number (default: 1).

per_page · integer

Results per page (default: 20, max: 100).

curl "https://api.dynamo-csms.com/api/v1/cpo/commands/CP-SITE42-001/history?from=2024-03-01T00:00:00Z&status=Rejected" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "commands": [
    {
      "command_id": "cmd_7f2a1b3c",
      "command": "start_session",
      "status": "Rejected",
      "parameters": {
        "connector_id": 2,
        "id_tag": "RFID-USER-UNKNOWN"
      },
      "charge_point_response": {
        "status": "Rejected"
      },
      "executed_at": "2024-03-05T10:22:00Z",
      "executed_by": "api_key:key_abc123",
      "response_time_ms": 203
    },
    {
      "command_id": "cmd_6e1a0b2c",
      "command": "set_unavailable",
      "status": "Rejected",
      "parameters": {
        "connector_id": 1
      },
      "charge_point_response": {
        "status": "Rejected"
      },
      "executed_at": "2024-03-03T08:14:00Z",
      "executed_by": "api_key:key_abc123",
      "response_time_ms": 198
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20
}

commands[].executed_by · string

The API key or user that triggered the command, in the format api_key:{key_id} or installer:{installer_id}.

---

Get organization-wide command history

GET /api/v1/cpo/commands/history

Returns command history across all charge points in your organization. Useful for audit trails, troubleshooting, and usage reporting.

charge_point_id · string

Filter to a specific charge point.

command · string

Filter by command type.

status · string

Filter by outcome.

executed_by · string

Filter by the API key or installer that sent the command.

from · string

ISO 8601 start of date range.

to · string

ISO 8601 end of date range.

page · integer

Page number (default: 1).

per_page · integer

Results per page (default: 20, max: 200).

curl "https://api.dynamo-csms.com/api/v1/cpo/commands/history?from=2024-03-01T00:00:00Z&to=2024-03-31T23:59:59Z&command=hard_reset" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "commands": [
    {
      "command_id": "cmd_1a2b3c4d",
      "charge_point_id": "CP-NORTH-012",
      "command": "hard_reset",
      "status": "Accepted",
      "parameters": {},
      "executed_at": "2024-03-15T02:00:00Z",
      "executed_by": "api_key:key_def456",
      "response_time_ms": 310
    },
    {
      "command_id": "cmd_2b3c4d5e",
      "charge_point_id": "CP-SOUTH-007",
      "command": "hard_reset",
      "status": "Timeout",
      "parameters": {},
      "executed_at": "2024-03-15T02:01:00Z",
      "executed_by": "api_key:key_def456",
      "response_time_ms": null,
      "error": "Charge point did not respond within 10 seconds"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20
}

---

Pagination

All history endpoints use cursor-free page-based pagination. The response always includes total, page, and per_page. To retrieve subsequent pages, increment page in your query:

# Page 1
curl "https://api.dynamo-csms.com/api/v1/cpo/commands/history?page=1&per_page=100"

# Page 2
curl "https://api.dynamo-csms.com/api/v1/cpo/commands/history?page=2&per_page=100"

---

Error responses

{
  "error": {
    "code": "charge_point_offline",
    "message": "CP-SITE42-003 is not currently connected to the OCPP server.",
    "charge_point_id": "CP-SITE42-003",
    "request_id": "req_9f3a2b1c"
  }
}

Status	Code	Meaning
400	validation_error	Missing or invalid field in request
400	invalid_command	Command name is not recognized
400	missing_parameters	Required parameters for this command are absent
400	too_many_targets	Bulk request exceeds 100 charge points
401	unauthorized	Missing or invalid API key
403	forbidden	Key lacks write:charge_points scope
404	not_found	Charge point does not belong to your organization
408	timeout	Charge point did not respond within the timeout
422	charge_point_offline	Charge point is not connected via OCPP
422	ocpp_rejected	Charge point returned Rejected
429	rate_limited	Exceeded command rate limit (10/s per charge point)