> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Firmware Management API — Fleet Update Rollouts

> View firmware versions across your fleet and manage rollouts using canary, rolling, or all-at-once strategies with pause and stage-execution controls.

The firmware management API lets you inspect what firmware version is running on every charger in your fleet and orchestrate updates safely using staged rollout strategies. You can deploy to a small canary group first, roll out incrementally, or push to all chargers simultaneously.

## List firmware versions across fleet

`GET /api/v1/cpo/fleet/firmware`

Returns a list of all distinct firmware versions currently running in your fleet along with the chargers on each version.

<ParamField query="site_id" type="string">
  Filter results to chargers at a specific site.
</ParamField>

<ParamField query="vendor" type="string">
  Filter by charger vendor/manufacturer.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/cpo/fleet/firmware" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "versions": [
    {
      "firmware_version": "3.5.0",
      "charger_count": 98,
      "vendor": "ABB",
      "model": "Terra AC",
      "release_date": "2024-04-01"
    },
    {
      "firmware_version": "3.4.1",
      "charger_count": 26,
      "vendor": "ABB",
      "model": "Terra AC",
      "release_date": "2023-11-15"
    }
  ],
  "total_chargers": 124
}
```

<ResponseField name="versions" type="object[]">
  <Expandable title="properties">
    <ResponseField name="firmware_version" type="string">Version string.</ResponseField>
    <ResponseField name="charger_count" type="number">Number of chargers running this version.</ResponseField>
    <ResponseField name="vendor" type="string">Charger manufacturer.</ResponseField>
    <ResponseField name="model" type="string">Charger model.</ResponseField>
    <ResponseField name="release_date" type="string">Date this firmware was released.</ResponseField>
  </Expandable>
</ResponseField>

***

## Create a firmware rollout

`POST /api/v1/cpo/firmware/rollout`

Defines and schedules a new firmware update rollout. The rollout does not begin automatically — call the [execute stage](#execute-rollout-stage) endpoint to start it.

Three rollout strategies are available:

* **canary** — deploys to a small initial subset, then waits for manual promotion before continuing to the rest
* **rolling** — deploys to chargers in sequential batches of a configurable size
* **all\_at\_once** — deploys to all specified chargers simultaneously

<ParamField body="charger_ids" type="string[]" required>
  List of `charge_point_id` values to include in the rollout.
</ParamField>

<ParamField body="firmware_url" type="string" required>
  HTTPS URL where chargers can download the firmware file. Must be publicly reachable by chargers.
</ParamField>

<ParamField body="strategy" type="string" required>
  Rollout strategy. Accepted values: `canary`, `rolling`, `all_at_once`.
</ParamField>

<ParamField body="batch_size" type="number">
  Number of chargers per batch. Used by the `rolling` strategy. Defaults to 10% of total chargers.
</ParamField>

<ParamField body="canary_count" type="number" default="1">
  Number of chargers in the initial canary stage. Used by the `canary` strategy.
</ParamField>

<ParamField body="retrieve_date" type="string">
  ISO 8601 date/time chargers should start downloading the firmware. Defaults to immediately on execution.
</ParamField>

```bash theme={null}
curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charger_ids": ["CP-001", "CP-002", "CP-003", "CP-004", "CP-005"],
    "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
    "strategy": "canary",
    "canary_count": 1
  }'
```

```json theme={null}
{
  "rollout_id": "rollout_4XNQP8",
  "strategy": "canary",
  "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
  "total_chargers": 5,
  "status": "pending",
  "stages": [
    {
      "stage": 1,
      "label": "Canary",
      "charger_ids": ["CP-001"],
      "status": "pending"
    },
    {
      "stage": 2,
      "label": "Rollout",
      "charger_ids": ["CP-002", "CP-003", "CP-004", "CP-005"],
      "status": "pending"
    }
  ],
  "created_at": "2024-06-15T09:00:00Z"
}
```

<ResponseField name="rollout_id" type="string">
  Unique identifier for the rollout.
</ResponseField>

<ResponseField name="status" type="string">
  Overall rollout status. One of: `pending`, `in_progress`, `paused`, `completed`, `failed`.
</ResponseField>

<ResponseField name="stages" type="object[]">
  <Expandable title="properties">
    <ResponseField name="stage" type="number">Stage number.</ResponseField>
    <ResponseField name="label" type="string">Human-readable stage label.</ResponseField>
    <ResponseField name="charger_ids" type="string[]">Chargers included in this stage.</ResponseField>
    <ResponseField name="status" type="string">Stage status: `pending`, `in_progress`, `completed`, `failed`.</ResponseField>
  </Expandable>
</ResponseField>

***

## Get rollout status

`GET /api/v1/cpo/firmware/rollout/{rollout_id}`

Returns the current status of a rollout and per-charger progress.

<ParamField path="rollout_id" type="string" required>
  The unique identifier of the rollout.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "rollout_id": "rollout_4XNQP8",
  "strategy": "canary",
  "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
  "status": "in_progress",
  "current_stage": 1,
  "stages": [
    {
      "stage": 1,
      "label": "Canary",
      "status": "in_progress",
      "chargers": [
        {
          "charge_point_id": "CP-001",
          "status": "downloading",
          "progress_percent": 62,
          "started_at": "2024-06-15T09:05:00Z",
          "completed_at": null
        }
      ]
    },
    {
      "stage": 2,
      "label": "Rollout",
      "status": "pending",
      "chargers": [
        { "charge_point_id": "CP-002", "status": "pending" },
        { "charge_point_id": "CP-003", "status": "pending" },
        { "charge_point_id": "CP-004", "status": "pending" },
        { "charge_point_id": "CP-005", "status": "pending" }
      ]
    }
  ],
  "created_at": "2024-06-15T09:00:00Z",
  "updated_at": "2024-06-15T09:05:30Z"
}
```

***

## Execute rollout stage

`POST /api/v1/cpo/firmware/rollout/{rollout_id}/execute-stage`

Advances the rollout to the next pending stage. For a `canary` rollout, call this once to deploy to the canary group, verify results, then call it again to release to the remaining chargers. For a `rolling` rollout, each call releases the next batch.

<ParamField path="rollout_id" type="string" required>
  The unique identifier of the rollout.
</ParamField>

```bash theme={null}
curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8/execute-stage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "rollout_id": "rollout_4XNQP8",
  "executed_stage": 2,
  "status": "in_progress",
  "chargers_triggered": ["CP-002", "CP-003", "CP-004", "CP-005"],
  "triggered_at": "2024-06-15T10:30:00Z"
}
```

<ResponseField name="executed_stage" type="number">
  The stage number that was just triggered.
</ResponseField>

<ResponseField name="chargers_triggered" type="string[]">
  Chargers in the stage that have been sent the update command.
</ResponseField>

***

## Pause a rollout

`POST /api/v1/cpo/firmware/rollout/{rollout_id}/pause`

Pauses an in-progress rollout. Chargers that are already downloading or installing will complete their current operation, but no new chargers will be triggered. Call [execute stage](#execute-rollout-stage) to resume.

<ParamField path="rollout_id" type="string" required>
  The unique identifier of the rollout.
</ParamField>

<ParamField body="reason" type="string">
  Optional explanation for why the rollout was paused. Stored for audit purposes.
</ParamField>

```bash theme={null}
curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8/pause" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Elevated error rate detected on canary charger CP-001"}'
```

```json theme={null}
{
  "rollout_id": "rollout_4XNQP8",
  "status": "paused",
  "paused_at": "2024-06-15T10:45:00Z",
  "reason": "Elevated error rate detected on canary charger CP-001"
}
```