Smart Charging API — Configure Site Load Management

Configure site power limits and load balancing strategies. View real-time allocation per charger, review history, and trigger manual rebalancing.

The smart charging API manages how available grid power is distributed across the chargers at each site. You set a maximum power ceiling and choose a strategy, and Dynamo automatically adjusts charge rates in real time to stay within that limit.

Three strategies are available:

• equal — available power is divided equally across all active chargers
• priority — chargers are ranked; higher-priority chargers receive more power
• scheduled — power allocation follows a time-based schedule you define

Configure smart charging for a site

PUT /api/v1/smart-charging/sites/{site_id}/config

Creates or replaces the smart charging configuration for a site. The configuration takes effect immediately.

site_id · string · required

The site to configure smart charging for.

max_power_kw · number · required

Maximum power budget for smart charging in kilowatts. Must not exceed the site’s grid connection capacity.

strategy · string · required

Load balancing strategy. Accepted values: equal, priority, scheduled.

min_power_per_charger_kw · number · default: "1.4"

Minimum power floor per charger. No charger will be allocated below this value while charging.

priority_order · string[]

Ordered list of charge_point_id values from highest to lowest priority. Required when strategy is priority.

curl -X PUT "https://api.dynamo-csms.com/api/v1/smart-charging/sites/site_01HZ4K8XVPQR3TY5N6M/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_power_kw": 100,
    "strategy": "priority",
    "min_power_per_charger_kw": 3.7,
    "priority_order": ["CP-001", "CP-002", "CP-003"]
  }'

{
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "max_power_kw": 100,
  "strategy": "priority",
  "min_power_per_charger_kw": 3.7,
  "priority_order": ["CP-001", "CP-002", "CP-003"],
  "updated_at": "2024-06-15T10:00:00Z"
}

site_id · string

The site this configuration applies to.

max_power_kw · number

Configured power ceiling.

strategy · string

Active load balancing strategy.

min_power_per_charger_kw · number

Minimum power floor per active charger.

priority_order · string[]

Ordered charger IDs for the priority strategy.

updated_at · string

ISO 8601 timestamp of the last configuration change.

---

Get smart charging config

GET /api/v1/smart-charging/sites/{site_id}/config

Returns the current smart charging configuration for a site.

site_id · string · required

The site to retrieve configuration for.

curl "https://api.dynamo-csms.com/api/v1/smart-charging/sites/site_01HZ4K8XVPQR3TY5N6M/config" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "max_power_kw": 100,
  "strategy": "equal",
  "min_power_per_charger_kw": 3.7,
  "priority_order": [],
  "updated_at": "2024-06-10T08:45:00Z"
}

---

Get current power allocation

GET /api/v1/smart-charging/sites/{site_id}/allocation

Returns the live power allocation for every active charger at the site. Use this to understand what each charger is currently being allowed to draw.

site_id · string · required

The site to retrieve allocation for.

curl "https://api.dynamo-csms.com/api/v1/smart-charging/sites/site_01HZ4K8XVPQR3TY5N6M/allocation" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "strategy": "equal",
  "total_budget_kw": 100,
  "total_allocated_kw": 73.6,
  "timestamp": "2024-06-15T16:00:00Z",
  "chargers": [
    {
      "charge_point_id": "CP-001",
      "allocated_kw": 18.4,
      "actual_kw": 17.9,
      "status": "Charging"
    },
    {
      "charge_point_id": "CP-002",
      "allocated_kw": 18.4,
      "actual_kw": 18.4,
      "status": "Charging"
    },
    {
      "charge_point_id": "CP-003",
      "allocated_kw": 18.4,
      "actual_kw": 12.1,
      "status": "Charging"
    },
    {
      "charge_point_id": "CP-004",
      "allocated_kw": 18.4,
      "actual_kw": 15.2,
      "status": "Charging"
    }
  ]
}

total_budget_kw · number

Total power budget configured for the site.

total_allocated_kw · number

Sum of allocations across all active chargers.

chargers · object[]

Show properties

charge_point_id · string

Charger identifier.

allocated_kw · number

Maximum power this charger is allowed to draw.

actual_kw · number

Power the charger is actually drawing at this moment.

status · string

Current charger status.

---

Get allocation history

GET /api/v1/smart-charging/sites/{site_id}/allocation/history

Returns a time series of past power allocation decisions for the site. Useful for auditing, reporting, and understanding how allocations have changed over time.

site_id · string · required

The site to retrieve history for.

from · string · required

ISO 8601 start date/time.

to · string · required

ISO 8601 end date/time.

granularity · string · default: "15min"

Time bucket size for aggregated results. Accepted values: 1min, 5min, 15min, 1hour.

curl "https://api.dynamo-csms.com/api/v1/smart-charging/sites/site_01HZ4K8XVPQR3TY5N6M/allocation/history?from=2024-06-15T00:00:00Z&to=2024-06-15T23:59:59Z&granularity=1hour" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "granularity": "1hour",
  "buckets": [
    {
      "period_start": "2024-06-15T08:00:00Z",
      "total_allocated_kw": 68.2,
      "total_actual_kw": 65.8,
      "active_chargers": 4
    },
    {
      "period_start": "2024-06-15T09:00:00Z",
      "total_allocated_kw": 82.5,
      "total_actual_kw": 79.1,
      "active_chargers": 5
    }
  ]
}

---

Trigger manual rebalance

POST /api/v1/smart-charging/sites/{site_id}/rebalance

Forces an immediate recalculation and reapplication of power limits across all active chargers at the site. Dynamo recalculates automatically whenever sessions start or stop, but you can use this endpoint to trigger an out-of-cycle rebalance — for example, after changing a site’s max power or updating priority order.

site_id · string · required

The site to rebalance.

curl -X POST "https://api.dynamo-csms.com/api/v1/smart-charging/sites/site_01HZ4K8XVPQR3TY5N6M/rebalance" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "rebalanced_at": "2024-06-15T16:05:00Z",
  "chargers_updated": 4,
  "new_allocation": [
    { "charge_point_id": "CP-001", "allocated_kw": 25.0 },
    { "charge_point_id": "CP-002", "allocated_kw": 25.0 },
    { "charge_point_id": "CP-003", "allocated_kw": 25.0 },
    { "charge_point_id": "CP-004", "allocated_kw": 25.0 }
  ]
}

rebalanced_at · string

ISO 8601 timestamp of when the rebalance was applied.

chargers_updated · number

Number of chargers whose limits were recalculated.

new_allocation · object[]

The updated allocation for each active charger.