Mist API Reference
Mist Automation Guide
HomeSDKsAPI ReferenceContext Plugin
UtilitiesUpgrade

upgradeOrgDevices

POST
/api/v1/orgs/{org_id}/devices/upgrade

Start an organization-level device upgrade job across selected sites. The request selects device type, sites, models, firmware versions, and upgrade strategy; AP-specific and Junos-specific options apply only where supported.

Authorization

Authorization<token>

Preferred authentication method for automation and integrations. Send the API token in the HTTP Authorization header.

Format: Authorization: Token {apitoken}

Notes:

  • An API token generated for a specific admin has the same privileges as that admin
  • An API token is automatically removed if it is not used for more than 90 days
  • SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed.

In: header

Path Parameters

org_id*string
Formatuuid

Request Body

application/json

Organization-wide device upgrade request

all_sites?boolean

If true, will upgrade all sites in this org; overrides site_ids

Defaultfalse
canary_phases?array<integer>

Only if strategy==canary. Canary phase percentages for the organization upgrade

Default

[  1,  10,  50,  100]
device_type?device_type

Device family selected for the organization upgrade. enum: ap, gateway, switch.

Value in

  • "ap"
  • "gateway"
  • "switch"
download_strategy?upgrade_org_devices_download_strategy

Firmware download orchestration strategy for the organization upgrade. enum: canary, big_bang, serial.

Default"big_bang"

Value in

  • "canary"
  • "big_bang"
  • "serial"
enable_p2p?boolean

For APs only. Whether to allow local AP-to-AP firmware upgrade

max_failure_percentage?upgrade_devices_max_failure_percentage

If strategy!=big_bang. Allowed failure percentage across the organization upgrade

Range0 <= value <= 100
Default5
max_failures?array<integer>

If strategy==canary. Per-phase failure limits for the organization upgrade

models?array<array<string>>

Device models selected for the organization upgrade

p2p_cluster_size?integer

For APs only. Size to split devices for peer-to-peer download batches; default 10

Range0 <= value
Default10
p2p_parallelism?integer

For APs only. Number of parallel peer-to-peer download batches to create. If not set, automatically determined based on device count (<=50 uses 1, 51-100 uses 3, >100 uses 10)

reboot_at?integer
Deprecated

Reboot start time in epoch seconds, default is start_time; deprecated, use reboot_datetime instead

reboot_datetime?string

Reboot start time in ISO 8601 format; default is start_datetime. Exclude timezone component to use site local timezone

reboot_strategy?upgrade_device_strategy

Device reboot orchestration strategy for selected devices. enum: big_bang, canary, rrm, serial.

Default"big_bang"

Value in

  • "big_bang"
  • "canary"
  • "rrm"
  • "serial"
rrm_first_batch_percentage?integer

For APs only and if strategy==rrm. Percentage of APs that need to be present in the first RRM batch

rrm_max_batch_percentage?integer

For APs only and if strategy==rrm. Max percentage of APs that need to be present in each RRM batch

rrm_mesh_upgrade?upgrade_device_rrm_mesh_upgrade

For APs only and if strategy==rrm. Mesh AP upgrade order for the organization upgrade. enum: parallel, sequential.

Default"sequential"

Value in

  • "parallel"
  • "sequential"
rrm_node_order?upgrade_device_rrm_node_order

For APs only and if strategy==rrm. AP ordering direction for RRM upgrade batches. enum: center_to_fringe, fringe_to_center.

Default"fringe_to_center"

Value in

  • "center_to_fringe"
  • "fringe_to_center"
rrm_slow_ramp?boolean

For APs only and if strategy==rrm. True will make rrm batch sizes slowly ramp up

rules?array<>

Selection rules used to choose devices for this organization upgrade

site_ids?array<>

Identifiers of sites used to limit the organization upgrade

snapshot?boolean

For Junos devices only. Perform recovery snapshot after device is rebooted

Defaultfalse
start_datetime?string

Firmware download start time in ISO 8601 format; default is now. Exclude timezone component to use site local timezone

start_time?integer
Deprecated

Firmware download start time in epoch seconds, default is now; deprecated, use start_datetime instead

strategy?upgrade_device_strategy_deprecated
Deprecated

Deprecated; use download_strategy and reboot_strategy instead. big_bang (upgrade all at once, no orchestration), serial (one at a time), canary, or rrm (AP only); default is big_bang

Default"big_bang"

Value in

  • "big_bang"
  • "canary"
  • "rrm"
  • "serial"
version?string
Deprecated

Deprecated; use versions instead. Specific firmware version, suggested, or alpha; default is latest

versions?array<>

Target firmware versions for this organization upgrade

Response Body

curl -X POST "https://example.com/api/v1/orgs/000000ab-00ab-00ab-00ab-0000000000ab/devices/upgrade" \  -H "Content-Type: application/json" \  -d '{}'
{  "enable_p2p": true,  "force": true,  "id": "31223085-405d-4b64-8aea-9c5b98098b4b",  "strategy": "big_bang",  "target_version": "0.14.29411",  "upgrades": [    {      "site_id": "1bbe6e79-2583-403c-be1a-9881b4691ab6",      "upgrade": {        "id": "473f6eca-6276-4993-bfeb-53cbbbba6f18",        "start_time": 1717658765,        "status": "upgrading",        "targets": {          "download_requested": [            "5c5b3550bd2e"          ],          "downloaded": [            "003e7316ff9e"          ],          "total": 4,          "upgraded": [            "5c5b3550bd2e",            "003e7316ff9e"          ]        }      }    }  ]}

listOrgDeviceUpgrades GET

List organization-level device upgrade jobs, including the site-level upgrade jobs created under each organization upgrade.

listOrgMxEdgeUpgrades GET

List Mist Edge upgrade requests for the organization, including status, rollout strategy, target versions, and per-status target counts.