Device

82 operations. Call any of them with omada_call_operation (or, in full tool mode, as a tool named by its operationId).

Operation	Method	Summary
getAdoptTip	GET	Get adopt tip
searchGlobalDevice	GET	Global search for devices returns the devices under the sites that have permissions.
exportAddFailDevices	GET	Export the device file that failed to add in GLOBAL view.
getAdoptAbleDevicesForGlobalBatchAdopt	GET	Batch get info of adopted device in global view.
exportGlobalDeviceList	POST	Export device list in GLOBAL view
getGlobalDeviceIncidentCounts	POST	Get global device incident counts
getGlobalKnownDeviceList	GET	Get global known device list
getGridAdoptedDevicesStatByGlobal	GET	Query the statistics for the list of global adopted devices.
getGlobalUnknownDeviceList	GET	Get global unknown device list
exportPreConfigDevicesGlobal	POST	Export preconfigured devices in GLOBAL view.
activeDeviceWithMultiSite	POST	Batch active devices with multi site
getAddDevicesStatusMultiSite	GET	Batch get added device status with multi site
addDevicesBySnWithMultiSite	POST	Batch add devices by SN with multi site
getCheckFirmwareTaskResult	GET	Get the result of the given check latest firmware task
onlineCheckUpgrade	POST	Start check latest firmware for all devices
moveSiteForAps	POST	Move aps to another site
downloadDeviceInfo	GET	Download device information.
batchAdopt	POST	batch adopt device
onlineRollingUpgradeByQuery	POST	Start batch rolling upgrade By Query
getDeviceWhiteList	GET	Get the whitelist list of devices.
getDeviceList	GET	Get site device list
retryAddDevice	POST	Retry add device
getDeviceAdoptResult	GET	Get device adopt result
checkMacType	GET	Check the device type by mac.
forceProvisionDevice	POST	Force provision device
forgetDevice	POST	Forget device
getSingleForgetProcess	GET	Get forget process of device
getFirmwareInfo	GET	Get the latest firmware info of the device
locateDevice	POST	Locate device
getSingleMoveSiteProcess	GET	Get move site process of device
getOnlineUpgradeRes	GET	Get online upgrade result
rebootDevice	POST	Reboot device
getDeviceRememberMe	GET	Get device remember Config
modifyDeviceRememberMe	POST	Modify device remember Config
deleteReplaceRecord	DELETE	Delete replace record
createReplaceRecord	POST	Create replace record
modifyReplaceRecord	PUT	Modify replace record
checkReplaceRecord	POST	Check replace record
moveSite	POST	Move site
adoptDevice	POST	Start adopt device
onlineUpgrade	POST	Start online upgrade
getOnlineTimeline	GET	Get device online timeline
getAllDeviceBySite	GET	Get device list info.
copyDeviceConfiguration	POST	Copy configuration
exportSiteDeviceList	POST	Export device list of site
getForgetProcess	GET	Get batch forget process
getDeviceIncidentCounts	POST	Get site device incident counts
locatePorts	POST	Locate multiple ports of multiple switches
getMoveSiteProcess	GET	Get batch move site process
addDevices	POST	Batch add devices (deprecated)
unbindActiveDeviceBySn	POST	Change the license from the old device to the new device
deleteTag	DELETE	Delete an existing tag
getTags	GET	Get tag list
modifyTag	PATCH	Modify an existing tag
addTag	POST	Create new tag
existUnSupportRadSecDevice	GET	Check for unsupported RadSec devices.
uploadUpgradeFile	POST	Upload device firmware
getUplinkDeviceInfo	POST	Query uplink information for specified device MAC addresses under the site.
getGridAdoptedBridgeDevicesBySite	GET	Get Bridge group grouped devices
getGridPendingBridgeDevicesBySite	GET	Get Bridge group ungrouped devices
getGridPendingDevicesBySite	GET	Get adoptable device list of target site
exportPreConfigDevices	POST	Export preconfigured devices of site.
activeDevice	POST	Batch active devices
getAddDevicesStatus	GET	Batch get added device status
addDevicesByDeviceKey	POST	Batch add devices by DEVICE KEY.
getManuallyUpgradeRes	GET	Get the result of the given manually upgrade task
cancelRollingUpgrade	DELETE	End the rolling upgrade task
getRollingUpgradeRes	GET	Get the result of the given rolling upgrade task
activeDeviceBySn	POST	Batch active devices by SN
addDevicesBySn	POST	Batch add devices by SN
unbindDeviceBySn	POST	Batch unbind devices by SN
manuallyUpgrade	POST	Start manually upgrade
onlineRollingUpgrade	POST	Start batch rolling upgrade
updateDeviceTag	POST	Set device tag for given devices
unbindDevice	POST	Batch unbind devices
getAutoSelectDevices	POST	Get auto select devices in quick-config page.
getMspAdoptTip	GET	MSP get adopt tip
exportMspAddFailDevices	GET	Export the device file that failed to add in MSP view.
retryAddDeviceByMsp	POST	retry add device in msp view
forgetDeviceForMsp	POST	Forget one device in MSP view.
addDevicesForMsp	POST	Batch add devices in MSP view
getAdoptAbleDevicesForMspBatchAdopt	GET	Batch get info of adopted device in MSP view.

getAdoptTip

GET /openapi/v1/{omadacId}/adopt-tip

Get adopt tip

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getAdoptTip"
}

Details, permissions and error codes

Get adopt tip
The interface requires one of the permissions:
Site Adopt Device Manager Access
Site Add Device Manager Access

searchGlobalDevice

GET /openapi/v1/{omadacId}/devices

Global search for devices returns the devices under the sites that have permissions.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
searchKey	query	string	yes	searchKey

// omada_call_operation
{
  "operationId": "searchGlobalDevice",
  "params": {
    "searchKey": "<searchKey>"
  }
}

Details, permissions and error codes

Global search for devices returns the devices under the sites that have permissions.
The interface requires one of the permissions:
Site Device Manager View Only

exportAddFailDevices

GET /openapi/v1/{omadacId}/devices/add/{operateId}/export

Export the device file that failed to add in GLOBAL view.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
operateId	path	string	yes	Operation ID
format	query	integer	yes	File format. 0: CSV, 1: XLSX

// omada_call_operation
{
  "operationId": "exportAddFailDevices",
  "params": {
    "operateId": "<operateId>",
    "format": "<format>"
  }
}

Details, permissions and error codes

Export the device file that failed to add in GLOBAL view. Format should be a number as follows. 0 means CSV , 1 means XLSX.
The interface requires one of the permissions:
Site Add Device Manager Access

getAdoptAbleDevicesForGlobalBatchAdopt

GET /openapi/v1/{omadacId}/devices/batch/info

Batch get info of adopted device in global view.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.name	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.status	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.ip	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchKey	query	string	no	Fuzzy query parameters, support field name,mac,ip
filters.tag	query	string	no	Filter query parameters, support field tag name

// omada_call_operation
{
  "operationId": "getAdoptAbleDevicesForGlobalBatchAdopt"
}

Details, permissions and error codes

Batch get info of adopted device in global view.
The interface requires one of the permissions:
Site Adopt Device Manager Access
Site Add Device Manager Access

exportGlobalDeviceList

POST /openapi/v1/{omadacId}/devices/export

Export device list in GLOBAL view

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

Request body — application/json (required) — schema ExportGlobalDeviceListOpenApiVO

Field	Type	Required	Description
mode	integer	yes	Value of mode should be 0 or 1 or 2. 0 : All columns, 1 : Customize the export columns, 2 : Default columns.
displayColumns	array<string>	no	In mode 1, the displayColumns cannot be empty. Allowed column name for input : ['deviceName', 'serialNumber', 'macAddress', 'ipAddress', 'publicIpAddress', 'ipv6Address', 'status', 'model', 'version', 'uplink', 'downlink', 'uptime', 'memoryUsage', 'cpuUsage', 'clients', 'downloadTraffic', 'uploadTraffic', 'loopback', 'hop', 'wlanGroup', 'override', 'radio2G', 'radio5G', 'radio6G', '2gClients', '5gClients', '6gClients', 'bSsid', 'txRate', 'rxRate', 'channel', 'channelUtilization2G', 'channelUtilization5G', 'channelUtilization6G', 'tags', 'lastSeen', 'configurationResult', 'licenseStatus'(pro controller exclusive), 'dueTime'(pro controller exclusive), 'series'(pro controller exclusive), 'health'(pro controller exclusive), 'stackGroup'(site view exclusive), 'uplinkDeviceName'(site view exclusive), 'uplinkDevicePort'(site view exclusive), 'linkSpeed'(site view exclusive), 'duplex'(site view exclusive)]
format	integer	yes	Format should be a value as follows. 0 means CSV , 1 means XLSX.
queryData	OpenApiQueryDataVO	no	(OpenApiQueryDataVO not expanded; call omada_get_schema "OpenApiQueryDataVO")

// omada_call_operation
{
  "operationId": "exportGlobalDeviceList",
  "body": "{...}"
}

Details, permissions and error codes

Export device list in GLOBAL view.
The interface requires one of the permissions:
Global Export Data Access

getGlobalDeviceIncidentCounts

POST /openapi/v1/{omadacId}/devices/incidents

Get global device incident counts

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

Request body — application/json (required) — schema DeviceIncidentCountRequestOpenApiVO

Field	Type	Required	Description
deviceList	array<string>	no	Device MAC addresses for which incident counts are requested.

// omada_call_operation
{
  "operationId": "getGlobalDeviceIncidentCounts",
  "body": "{...}"
}

Details, permissions and error codes

Get incident counts for the specified devices globally.
The interface requires one of the permissions:
Site Device Manager View Only
Incidents Page View Only

getGlobalKnownDeviceList

GET /openapi/v1/{omadacId}/devices/known-devices

Get global known device list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.mac	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchMacs	query	string	no	Fuzzy query parameters, support field mac
searchNames	query	string	no	Fuzzy query parameters, support field name
searchModels	query	string	no	Fuzzy query parameters, support field model
searchSns	query	string	no	Fuzzy query parameters, support field sn
filters.tag	query	string	no	Filter query parameters, support field tag ID
filters.deviceSeriesType	query	string	no	Filter query parameters, support field Device series type. 0: basic; 1: pro.

// omada_call_operation
{
  "operationId": "getGlobalKnownDeviceList"
}

Details, permissions and error codes

Get global known device list.
The interface requires one of the permissions:
Site Device Manager View Only
MSP Device Manager View Only

getGridAdoptedDevicesStatByGlobal

GET /openapi/v1/{omadacId}/devices/stat

Query the statistics for the list of global adopted devices.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.name	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.status	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.ip	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchKey	query	string	no	Fuzzy query parameters, support field name,mac,ip
filters.tag	query	string	no	Filter query parameters, support field tag name

// omada_call_operation
{
  "operationId": "getGridAdoptedDevicesStatByGlobal"
}

Details, permissions and error codes

Query the statistics for the list of global adopted devices.
The interface requires one of the permissions:
Site Device Manager View Only
MSP Device Manager View Only

getGlobalUnknownDeviceList

GET /openapi/v1/{omadacId}/devices/unknown-devices

Get global unknown device list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.mac	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchMacs	query	string	no	Fuzzy query parameters, support field mac
searchNames	query	string	no	Fuzzy query parameters, support field name
searchModels	query	string	no	Fuzzy query parameters, support field model

// omada_call_operation
{
  "operationId": "getGlobalUnknownDeviceList"
}

Details, permissions and error codes

Get global unknown device list.
The interface requires one of the permissions:
Site Device Manager View Only
MSP Device Manager View Only

exportPreConfigDevicesGlobal

POST /openapi/v1/{omadacId}/migrate/exportPreDevice

Export preconfigured devices in GLOBAL view.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

// omada_call_operation
{
  "operationId": "exportPreConfigDevicesGlobal"
}

Details, permissions and error codes

Export preconfigured devices in GLOBAL view.
The interface requires one of the permissions:
Global Other Setting Modify

activeDeviceWithMultiSite

POST /openapi/v1/{omadacId}/multi-devices/active

Batch active devices with multi site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

Request body — application/json (required) — schema ActiveDeviceMultiSiteOpenApiVO

Field	Type	Required	Description
activePairList	array<ActivePairMultiSiteOpenApiDTO>	yes
category	string	yes	It should be a value as follows: basic; ap; l2Switch; l3Switch; gateway

// omada_call_operation
{
  "operationId": "activeDeviceWithMultiSite",
  "body": "{...}"
}

Details, permissions and error codes

Batch active devices with multi site.
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

getAddDevicesStatusMultiSite

GET /openapi/v1/{omadacId}/multi-devices/add/{operateId}/status

Batch get added device status with multi site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
operateId	path	string	yes	Add device operation ID

// omada_call_operation
{
  "operationId": "getAddDevicesStatusMultiSite",
  "params": {
    "operateId": "<operateId>"
  }
}

Details, permissions and error codes

Batch get added device status with multi site.
The interface requires one of the permissions:
Site Add Device Manager Access

addDevicesBySnWithMultiSite

POST /openapi/v1/{omadacId}/multi-devices/sn-add

Batch add devices by SN with multi site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)

Request body — application/json (required) — schema DeviceListAddMultiSiteBySnOpenApiVO

Field	Type	Required	Description
devices	array<AddDeviceWithSiteBySnOpenApiVO>	yes	Add devices list

// omada_call_operation
{
  "operationId": "addDevicesBySnWithMultiSite",
  "body": "{...}"
}

Details, permissions and error codes

Batch add devices by SN with multi site.
The interface requires one of the permissions:
Site Adopt Device Manager Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39039 - Too many devices imported at a time.
-39042 - Invalid device information in the imported file.
-39043 - Importing... Please wait.
-53125 - The Add Devices function has been locked due to too many invalid attempts.

getCheckFirmwareTaskResult

GET /openapi/v1/{omadacId}/sites/{siteId}/all-devices/check-latest-firmware-tasks/{taskId}

Get the result of the given check latest firmware task

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
taskId	path	string	yes	Task ID. The ID is the return value of 'Start check latest firmware for all devices' interface

// omada_call_operation
{
  "operationId": "getCheckFirmwareTaskResult",
  "params": {
    "siteId": "<siteId>",
    "taskId": "<taskId>"
  }
}

Details, permissions and error codes

Get the result of the firmware update task, containing a list of devices with firmware updates
The interface requires one of the permissions:
Site Device Manager Modify

onlineCheckUpgrade

POST /openapi/v1/{omadacId}/sites/{siteId}/all-devices/start-check-latest-firmware

Start check latest firmware for all devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "onlineCheckUpgrade",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Start a task to query the latest firmware of all devices in the cloud.
The interface requires one of the permissions:
Site Device Manager Modify

moveSiteForAps

POST /openapi/v1/{omadacId}/sites/{siteId}/aps/site-move

Move aps to another site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ApMoveSiteOpenApiVO

Field	Type	Required	Description
targetSite	string	yes	Target site ID
apMacs	array<string>	no	aps mac list

// omada_call_operation
{
  "operationId": "moveSiteForAps",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Move aps to another site. If you want to move networked bridge APs, ensure all APs in the bridge network are in movable state and move them at the same time. This interface will not move non-AP devices.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1005 - Operation forbidden.
-33000 - This site does not exist.
-39050 - This device does not exist.
-39081 - The device is already in the target site.
-39094 - The site type does not match the device series, pro site can only manage Omada Pro device.
-39095 - The site type does not match the device series, basic site can only manage Omada device.
-39363 - Cannot move the bridge AP(s). Please ensure all the APs in the bridge network are in movable state and move them at the same time.
-44261 - The device does not support cluster and can only be adopted to its own site.

downloadDeviceInfo

GET /openapi/v1/{omadacId}/sites/{siteId}/cmd/devices/{deviceMac}/downloadDeviceInfo/{type}

Download device information.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF
type	path	string	yes	Device Type. Supported type: ap, gateway, switch, olt.

// omada_call_operation
{
  "operationId": "downloadDeviceInfo",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>",
    "type": "<type>"
  }
}

Details, permissions and error codes

Download device information.
The interface requires one of the permissions:
Site Device Manager View Only

batchAdopt

POST /openapi/v1/{omadacId}/sites/{siteId}/cmd/devices/batch-adopt

batch adopt device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema BatchAdoptDeviceRequest

Field	Type	Required	Description
username	string	no	Adopt device username. It should contain 1 to 64 characters.
password	string	no	Adopt device password. It should contain 1 to 64 characters.
macs	array<string>	no	MAC list of devices. E.g. AA-BB-CC-DD-11-22

// omada_call_operation
{
  "operationId": "batchAdopt",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

batch adopt device.This interface does not return the actual adoptive result,you need to use the interface:Get device adopt result to obtain the adoptive result
The interface requires one of the permissions:
Site Adopt Device Manager Access
Site Add Device Manager Access

onlineRollingUpgradeByQuery

POST /openapi/v1/{omadacId}/sites/{siteId}/cmd/devices/onlineRollingUpgrade

Start batch rolling upgrade By Query

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
filters.ecspFirstVersion	query	string	no	Filter query parameters, support field ecsp first version. 1: ecsp v1; 2: ecsp v2

Request body — application/json (required) — schema RollingUpgradeRequest

Field	Type	Required	Description
macs	array<string>	no	MAC list of devices. E.g. AA-BB-CC-DD-11-22

// omada_call_operation
{
  "operationId": "onlineRollingUpgradeByQuery",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Perform batch online upgrades of devices in a specific order within the site, and filter them using filter conditions. It is recommended to check the firmware update status before the operation, otherwise the firmware may not be the latest version
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39020 - Failed to upgrade because no device is ready for upgrading.

getDeviceWhiteList

GET /openapi/v1/{omadacId}/sites/{siteId}/device-white-list

Get the whitelist list of devices.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getDeviceWhiteList",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get the whitelist list of devices.
The interface requires one of the permissions:
Site Device Manager View Only

getDeviceList

GET /openapi/v1/{omadacId}/sites/{siteId}/devices

Get site device list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.name	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.status	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.ip	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchKey	query	string	no	Fuzzy query parameters, support field name,mac,ip
filters.tag	query	string	no	Filter query parameters, support field tag name

// omada_call_operation
{
  "operationId": "getDeviceList",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get site device list.
The interface requires one of the permissions:
Site Device Manager View Only
MSP Device Manager View Only

retryAddDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/add/retry

Retry add device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema RetryAddDeviceOpenApiVO

Field	Type	Required	Description
username	string	no	retry add device username
password	string	no	retry add device password

// omada_call_operation
{
  "operationId": "retryAddDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Retry add device
The interface requires one of the permissions:
Site Adopt Device Manager Access
Site Add Device Manager Access

getDeviceAdoptResult

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/adopt-result

Get device adopt result

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "getDeviceAdoptResult",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Get device adopt result.
The interface requires one of the permissions:
Site Adopt Device Manager Access

checkMacType

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/check-mac-type

Check the device type by mac.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "checkMacType",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Check the device type by mac.
The interface requires one of the permissions:
Site Log & Audit Log Manager View Only

forceProvisionDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/force-provision

Force provision device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "forceProvisionDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Force provision device.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1 - Something went wrong. Please try again later or contact our technical support.
-1001 - Invalid request parameters.
-1200 - You have been logged out of the controller. This may have been caused by web application switching, data restore, reboot, session timeout or disabled cloud access. Please try to log in again later.
-39050 - This device does not exist.
-39051 - Operation failed. Please try again later.

forgetDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/forget

Forget device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "forgetDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Forget device.
The interface requires one of the permissions:
Site Device Manager Modify
MSP Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39013 - Deletion failed. This device does not exist.
-39014 - To avoid damage, please do not forget the device during upgrading.
-39054 - Controller failed to forget device.
-39055 - Controller has forgotten the device but failed to reset it.

getSingleForgetProcess

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/forget/{forgetId}/status

Get forget process of device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF
forgetId	path	string	yes	Forget ID

// omada_call_operation
{
  "operationId": "getSingleForgetProcess",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>",
    "forgetId": "<forgetId>"
  }
}

Details, permissions and error codes

Get forget process of one device from batch-forget. The expire time of result for each device is 300 seconds.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1 - Something went wrong. Please try again later or contact our technical support.
-1001 - Invalid request parameters.
-1200 - You have been logged out of the controller. This may have been caused by web application switching, data restore, reboot, session timeout or disabled cloud access. Please try to log in again later.
-39050 - This device does not exist.
-39104 - The current request parameters do not exist or the request result has expired.

getFirmwareInfo

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/latest-firmware-info

Get the latest firmware info of the device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "getFirmwareInfo",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Get latest firmware info of the device, including the latest firmware version and release logs.
The interface requires one of the permissions:
Site Device Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39050 - This device does not exist.

locateDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/locate

Locate device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema LocateDeviceRequest

Field	Type	Required	Description
locateEnable	boolean	no
portList	array<integer>	no	Ports to be located

// omada_call_operation
{
  "operationId": "locateDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Locate device.
The interface requires one of the permissions:
Site Device Manager Modify
Site Clients Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39005 - Failed to adopt this device because the device is not connected.
-39121 - One or multiple devices do not support port locating.

getSingleMoveSiteProcess

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/move/{moveSiteId}/status

Get move site process of device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF
moveSiteId	path	string	yes	Move Site ID

// omada_call_operation
{
  "operationId": "getSingleMoveSiteProcess",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>",
    "moveSiteId": "<moveSiteId>"
  }
}

Details, permissions and error codes

Get move site process of one device from batch-move-site. The expire time of result for each device is 300 seconds
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1 - Something went wrong. Please try again later or contact our technical support.
-1001 - Invalid request parameters.
-1200 - You have been logged out of the controller. This may have been caused by web application switching, data restore, reboot, session timeout or disabled cloud access. Please try to log in again later.
-39050 - This device does not exist.
-39104 - The current request parameters do not exist or the request result has expired.

getOnlineUpgradeRes

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/online-upgrade-result

Get online upgrade result

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "getOnlineUpgradeRes",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Get the result of the online upgrade.
The interface requires one of the permissions:
Site Device Manager Modify

rebootDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/reboot

Reboot device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "rebootDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Reboot device.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39006 - Operation failed. This device does not exist.
-39007 - Failed to reboot this device because the device is not connected.
-39008 - To avoid damage, please do not reboot the device during upgrading.
-39009 - Rebooting... Please wait.
-39010 - Failed to reboot. The device is synchronizing configurations.
-39011 - Failed to reboot. The controller is making provision for the device.
-39012 - Failed to send the reboot command to the device.

getDeviceRememberMe

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/remember

Get device remember Config

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "getDeviceRememberMe",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Get device remember Config
The interface requires one of the permissions:
Site Device Manager View Only

modifyDeviceRememberMe

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/remember

Modify device remember Config

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema DeviceRememberConfig

Field	Type	Required	Description
remember	integer	no	The remember configuration of the device, 0 means disable, 1 means enable, 2 means follow site.

// omada_call_operation
{
  "operationId": "modifyDeviceRememberMe",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify device remember Config
The interface requires one of the permissions:
Site Device Manager Modify

deleteReplaceRecord

DELETE /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/replace-device

Delete replace record

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "deleteReplaceRecord",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Delete replace record.
The interface requires one of the permissions:
Site Device Manager Modify

createReplaceRecord

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/replace-device

Create replace record

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema DeviceReplaceSettingVO

Field	Type	Required	Description
destinationDeviceKey	string	yes	Device Key of the device.
username	string	no	User Name.
password	string	no	password.

// omada_call_operation
{
  "operationId": "createReplaceRecord",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Create replace record.
The interface requires one of the permissions:
Site Device Manager Modify

modifyReplaceRecord

PUT /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/replace-device

Modify replace record

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema DeviceReplaceSettingVO

Field	Type	Required	Description
destinationDeviceKey	string	yes	Device Key of the device.
username	string	no	User Name.
password	string	no	password.

// omada_call_operation
{
  "operationId": "modifyReplaceRecord",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify replace record.
The interface requires one of the permissions:
Site Device Manager Modify

checkReplaceRecord

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/replace-device/check

Check replace record

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema CheckReplaceVO

Field	Type	Required	Description
deviceKey	string	yes	Device Key.

// omada_call_operation
{
  "operationId": "checkReplaceRecord",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Check replace record.
The interface requires one of the permissions:
Site Device Manager Modify

moveSite

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/site-move

Move site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema DeviceMoveSiteOpenApiVO

Field	Type	Required	Description
targetSite	string	yes	Target site ID

// omada_call_operation
{
  "operationId": "moveSite",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Move the device to another site. If you want to move a networked bridge AP, use the "batch move ap site" interface to move all APs in the bridge network at the same time.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33421 - The gateway model in the target site is different from the gateway model configured in the WAN Settings Overrides in the original site.
-39050 - This device does not exist.
-39081 - The device is already in the target site.
-39094 - The site type does not match the device series, pro site can only manage Omada Pro device.
-39095 - The site type does not match the device series, basic site can only manage Omada device.
-39363 - Cannot move the bridge AP(s). Please ensure all the APs in the bridge network are in movable state and move them at the same time.
-39502 - Failed to move the gateway. The target site already has a gateway.
-44261 - The device does not support cluster and can only be adopted to its own site.

adoptDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/start-adopt

Start adopt device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema AdoptDeviceRequest

Field	Type	Required	Description
username	string	no	Adopt device username. It should contain 1 to 64 characters.
password	string	no	Adopt device password. It should contain 1 to 64 characters.

// omada_call_operation
{
  "operationId": "adoptDevice",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Start adopt device.This interface does not return the actual adoptive result, you need to use the interface:Get device adopt result to obtain the adoptive result
The interface requires one of the permissions:
Site Adopt Device Manager Access

onlineUpgrade

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/start-online-upgrade

Start online upgrade

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "onlineUpgrade",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Upgrade the device with the latest firmware in the cloud. It is suggested to check firmware update before the operation, or the firmware might not be the latest
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39020 - Failed to upgrade because no device is ready for upgrading.
-39026 - The upgrade file is the same with the current version.

getOnlineTimeline

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/{deviceMac}/timeline

Get device online timeline

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF
queryParam	query	TimeIntervalQueryOpenApiVO	no	Object: its fields (start, end) are sent as separate query parameters.

// omada_call_operation
{
  "operationId": "getOnlineTimeline",
  "params": {
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Get device online timeline
The interface requires one of the permissions:
Site Device Manager View Only

getAllDeviceBySite

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/all

Get device list info.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getAllDeviceBySite",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get device list info.
The interface requires one of the permissions:
Site Device Manager View Only
Site Dashboard Manager View Only

copyDeviceConfiguration

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/copy

Copy configuration

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeviceCopyConfigurationOpenApiVO

Field	Type	Required	Description
sourceMac	string	yes	Source device MAC, like AA-BB-CC-DD-EE-FF
targetMac	string	yes	Target device MAC, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "copyDeviceConfiguration",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Copy the configuration of one device to another device of the same model. Only for switch and access point.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39050 - This device does not exist.
-39056 - Failed to copy config because of source device not exist.
-39057 - Failed to copy config because of the copied device is different from the model of the source device.

exportSiteDeviceList

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/export

Export device list of site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ExportGlobalDeviceListOpenApiVO

Field	Type	Required	Description
mode	integer	yes	Value of mode should be 0 or 1 or 2. 0 : All columns, 1 : Customize the export columns, 2 : Default columns.
displayColumns	array<string>	no	In mode 1, the displayColumns cannot be empty. Allowed column name for input : ['deviceName', 'serialNumber', 'macAddress', 'ipAddress', 'publicIpAddress', 'ipv6Address', 'status', 'model', 'version', 'uplink', 'downlink', 'uptime', 'memoryUsage', 'cpuUsage', 'clients', 'downloadTraffic', 'uploadTraffic', 'loopback', 'hop', 'wlanGroup', 'override', 'radio2G', 'radio5G', 'radio6G', '2gClients', '5gClients', '6gClients', 'bSsid', 'txRate', 'rxRate', 'channel', 'channelUtilization2G', 'channelUtilization5G', 'channelUtilization6G', 'tags', 'lastSeen', 'configurationResult', 'licenseStatus'(pro controller exclusive), 'dueTime'(pro controller exclusive), 'series'(pro controller exclusive), 'health'(pro controller exclusive), 'stackGroup'(site view exclusive), 'uplinkDeviceName'(site view exclusive), 'uplinkDevicePort'(site view exclusive), 'linkSpeed'(site view exclusive), 'duplex'(site view exclusive)]
format	integer	yes	Format should be a value as follows. 0 means CSV , 1 means XLSX.
queryData	OpenApiQueryDataVO	no	(OpenApiQueryDataVO not expanded; call omada_get_schema "OpenApiQueryDataVO")

// omada_call_operation
{
  "operationId": "exportSiteDeviceList",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Export device list of site.
The interface requires one of the permissions:
Site Export Data Access

getForgetProcess

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/forget/{forgetId}/status

Get batch forget process

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
forgetId	path	string	yes	Forget ID

// omada_call_operation
{
  "operationId": "getForgetProcess",
  "params": {
    "siteId": "<siteId>",
    "forgetId": "<forgetId>"
  }
}

Details, permissions and error codes

Get process of the batch forget operation. The expire time of result is 300 seconds.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1 - Something went wrong. Please try again later or contact our technical support.
-1001 - Invalid request parameters.
-1200 - You have been logged out of the controller. This may have been caused by web application switching, data restore, reboot, session timeout or disabled cloud access. Please try to log in again later.
-39104 - The current request parameters do not exist or the request result has expired.

getDeviceIncidentCounts

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/incidents

Get site device incident counts

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeviceIncidentCountRequestOpenApiVO

Field	Type	Required	Description
deviceList	array<string>	no	Device MAC addresses for which incident counts are requested.

// omada_call_operation
{
  "operationId": "getDeviceIncidentCounts",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Get incident counts for the specified devices in a site.
The interface requires one of the permissions:
Site Device Manager View Only
Incidents Page View Only

locatePorts

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/locate/switch-ports

Locate multiple ports of multiple switches

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema LocateOswPortsOpenApiVO

Field	Type	Required	Description
portListVOs	array<OswNormalPortListVO>	no	List of Switch MAC and ports.
stackPortListVOs	array<OswStackPortListVO>	no	List of Stack ID and Standard Ports.
locateEnable	boolean	yes	Whether locate function is enabled

// omada_call_operation
{
  "operationId": "locatePorts",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Locate multiple ports of multiple switches
The interface requires one of the permissions:
Site Device Manager Modify
Device Config Page Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39005 - Failed to adopt this device because the device is not connected.
-39121 - One or multiple devices do not support port locating.

getMoveSiteProcess

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/move/{moveSiteId}/status

Get batch move site process

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
moveSiteId	path	string	yes	Move Site ID

// omada_call_operation
{
  "operationId": "getMoveSiteProcess",
  "params": {
    "siteId": "<siteId>",
    "moveSiteId": "<moveSiteId>"
  }
}

Details, permissions and error codes

Get process of the batch move site operation. The expire time of result is 300 seconds.
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-1 - Something went wrong. Please try again later or contact our technical support.
-1001 - Invalid request parameters.
-1200 - You have been logged out of the controller. This may have been caused by web application switching, data restore, reboot, session timeout or disabled cloud access. Please try to log in again later.
-39104 - The current request parameters do not exist or the request result has expired.

addDevices

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/multi-add

Deprecated

This operation is deprecated.

Batch add devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeviceListAddOpenApiVO

Field	Type	Required	Description
devices	array<AddDeviceVO>	yes	Add devices list

// omada_call_operation
{
  "operationId": "addDevices",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch add devices.This interface has been deprecated. Please use the following interface instead: Batch add devices by SN
The interface requires one of the permissions:
Site Adopt Device Manager Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39039 - Too many devices imported at a time.
-39042 - Invalid device information in the imported file.
-39043 - Importing... Please wait.
-53125 - The Add Devices function has been locked due to too many invalid attempts.

unbindActiveDeviceBySn

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/sn-unbind-active

Change the license from the old device to the new device

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema UnbindActiveDeviceSnOpenApiVO

Field	Type	Required	Description
oldSn	string	yes	Old serial number. It should contains 13 characters
newSn	string	yes	New serial number. It should contains 13 characters

// omada_call_operation
{
  "operationId": "unbindActiveDeviceBySn",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Change the license from the old device to the new device (using the same license).
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

deleteTag

DELETE /openapi/v1/{omadacId}/sites/{siteId}/devices/tag

Delete an existing tag

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeleteTagOpenApiVO

Field	Type	Required	Description
tagId	string	yes	Tag ID

// omada_call_operation
{
  "operationId": "deleteTag",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Delete an existing tag.
The interface requires one of the permissions:
Site Device Manager Modify

getTags

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/tag

Get tag list

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getTags",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get tag list.
The interface requires one of the permissions:
Site Device Manager View Only
Site Map Manager View Only

modifyTag

PATCH /openapi/v1/{omadacId}/sites/{siteId}/devices/tag

Modify an existing tag

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ModifyTagOpenApiVO

Field	Type	Required	Description
tagId	string	yes	Tag ID
name	string	yes	Tag name should contain 1 to 128 ASCII characters.

// omada_call_operation
{
  "operationId": "modifyTag",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify an existing tag.
The interface requires one of the permissions:
Site Device Manager Modify

addTag

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/tag

Create new tag

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema TagOpenApiVO

Field	Type	Required	Description
name	string	yes	Tag name should contain 1 to 128 ASCII characters.

// omada_call_operation
{
  "operationId": "addTag",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Create new tag.
The interface requires one of the permissions:
Site Device Manager Modify

existUnSupportRadSecDevice

GET /openapi/v1/{omadacId}/sites/{siteId}/devices/un-support-radsec

Check for unsupported RadSec devices.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "existUnSupportRadSecDevice",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get the result of detecting devices that do not support the RadSec feature.
The interface requires one of the permissions:
Site Device Manager View Only

uploadUpgradeFile

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/upgrade-file

Upload device firmware

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — multipart/form-data (optional). File field(s): file.

// omada_call_operation
{
  "operationId": "uploadUpgradeFile",
  "params": {
    "siteId": "<siteId>"
  },
  "files": {
    "file": {
      "path": "/path/to/file"
    }
  }
}

Details, permissions and error codes

Upload device firmware for manually upgrade.
The interface requires one of the permissions:
Site Manual Firmware Upgrade Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39021 - Invalid file for upgrading.
-39022 - This file size is too large.

getUplinkDeviceInfo

POST /openapi/v1/{omadacId}/sites/{siteId}/devices/uplink-info

Query uplink information for specified device MAC addresses under the site.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema QueryDeviceUplinkOpenApiVO

Field	Type	Required	Description
deviceMacs	array<string>	no	The list of deviceMac that require querying uplink device information.

// omada_call_operation
{
  "operationId": "getUplinkDeviceInfo",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Query uplink information for specified device MAC addresses under the site.
The interface requires one of the permissions:
Site Device Manager View Only
MSP Device Manager View Only
Incidents Page View Only

getGridAdoptedBridgeDevicesBySite

GET /openapi/v1/{omadacId}/sites/{siteId}/grid/bridge-devices/adopted

Get Bridge group grouped devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.mac	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchMacs	query	string	no	Fuzzy query parameters, support field mac
searchNames	query	string	no	Fuzzy query parameters, support field name
searchModels	query	string	no	Fuzzy query parameters, support field model
searchSns	query	string	no	Fuzzy query parameters, support field sn
filters.tag	query	string	no	Filter query parameters, support field tag ID
filters.deviceSeriesType	query	string	no	Filter query parameters, support field Device series type. 0: basic; 1: pro.

// omada_call_operation
{
  "operationId": "getGridAdoptedBridgeDevicesBySite",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get Bridge group grouped devices.
The interface requires one of the permissions:
Site Device Manager View Only

getGridPendingBridgeDevicesBySite

GET /openapi/v1/{omadacId}/sites/{siteId}/grid/bridge-devices/pending

Get Bridge group ungrouped devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.mac	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchMacs	query	string	no	Fuzzy query parameters, support field mac
searchNames	query	string	no	Fuzzy query parameters, support field name
searchModels	query	string	no	Fuzzy query parameters, support field model
searchSns	query	string	no	Fuzzy query parameters, support field sn
filters.tag	query	string	no	Filter query parameters, support field tag ID
filters.deviceSeriesType	query	string	no	Filter query parameters, support field Device series type. 0: basic; 1: pro.

// omada_call_operation
{
  "operationId": "getGridPendingBridgeDevicesBySite",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get Bridge group ungrouped devices.
The interface requires one of the permissions:
Site Device Manager View Only

getGridPendingDevicesBySite

GET /openapi/v1/{omadacId}/sites/{siteId}/grid/devices/pending

Get adoptable device list of target site

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
searchKey	query	string	no	searchKey

// omada_call_operation
{
  "operationId": "getGridPendingDevicesBySite",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get adoptable device list of target site.
The interface requires one of the permissions:
Site Device Manager View Only

exportPreConfigDevices

POST /openapi/v1/{omadacId}/sites/{siteId}/migrate/exportPreDevice

Export preconfigured devices of site.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "exportPreConfigDevices",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Export preconfigured devices of site.
The interface requires one of the permissions:
Global Other Setting Modify

activeDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/active

Batch active devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ActiveDeviceOpenApiVO

Field	Type	Required	Description
activePairList	array<ActivePairOpenApiDTO>	yes
category	string	yes	It should be a value as follows: basic; ap; l2Switch; l3Switch; gateway

// omada_call_operation
{
  "operationId": "activeDevice",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch active devices.
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

getAddDevicesStatus

GET /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/add/{operateId}/status

Batch get added device status

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
operateId	path	string	yes	Add device operation ID

// omada_call_operation
{
  "operationId": "getAddDevicesStatus",
  "params": {
    "siteId": "<siteId>",
    "operateId": "<operateId>"
  }
}

Details, permissions and error codes

Batch get added device status.
The interface requires one of the permissions:
Site Add Device Manager Access

addDevicesByDeviceKey

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/devicekey-add

Batch add devices by DEVICE KEY.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeviceListAddByDevicekeyOpenApiVO

Field	Type	Required	Description
devices	array<AddDeviceByDevicekeyOpenApiVO>	yes	add devices list

// omada_call_operation
{
  "operationId": "addDevicesByDeviceKey",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch add devices by DEVICE KEY.
The interface requires one of the permissions:
Site Adopt Device Manager Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39039 - Too many devices imported at a time.
-39042 - Invalid device information in the imported file.
-39043 - Importing... Please wait.
-53125 - The Add Devices function has been locked due to too many invalid attempts.

getManuallyUpgradeRes

GET /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/manually-upgrade-tasks/{taskId}

Get the result of the given manually upgrade task

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
taskId	path	string	yes	Task ID. The ID is the return value of 'Start manually upgrade' interface.

// omada_call_operation
{
  "operationId": "getManuallyUpgradeRes",
  "params": {
    "siteId": "<siteId>",
    "taskId": "<taskId>"
  }
}

Details, permissions and error codes

Get the result of the manually upgrade task. The results include whether the task is finished and how many devices have not completed the upgrade.
The interface requires one of the permissions:
Site Manual Firmware Upgrade Access

cancelRollingUpgrade

DELETE /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/rolling-upgrade-tasks/{taskId}

End the rolling upgrade task

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
taskId	path	string	yes	Task ID. The ID is the return value of 'Start batch rolling upgrade' interface.

// omada_call_operation
{
  "operationId": "cancelRollingUpgrade",
  "params": {
    "siteId": "<siteId>",
    "taskId": "<taskId>"
  }
}

Details, permissions and error codes

Cancel the rolling upgrade task in the site. But the devices which have completed the upgrade will not be rolled back to the old version
The interface requires one of the permissions:
Site Device Manager Modify

getRollingUpgradeRes

GET /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/rolling-upgrade-tasks/{taskId}

Get the result of the given rolling upgrade task

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
taskId	path	string	yes	Task ID. The ID is the return value of 'Start batch rolling upgrade' interface.

// omada_call_operation
{
  "operationId": "getRollingUpgradeRes",
  "params": {
    "siteId": "<siteId>",
    "taskId": "<taskId>"
  }
}

Details, permissions and error codes

Get the result of the rolling upgrade task. The results include whether the task is finished and how many devices have not completed the upgrade.
The interface requires one of the permissions:
Site Device Manager Modify

activeDeviceBySn

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/sn-active

Batch active devices by SN

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ActiveDeviceSnOpenApiVO

Field	Type	Required	Description
activePairList	array<ActivePairSnOpenApiDTO>	yes
category	string	yes	It should be a value as follows: basic; ap; l2Switch; l3Switch; gateway

// omada_call_operation
{
  "operationId": "activeDeviceBySn",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch active devices by SN.
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

addDevicesBySn

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/sn-add

Batch add devices by SN

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema DeviceListAddBySnOpenApiVO

Field	Type	Required	Description
devices	array<AddDeviceBySnOpenApiVO>	yes	Add devices list

// omada_call_operation
{
  "operationId": "addDevicesBySn",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch add devices by SN.
The interface requires one of the permissions:
Site Adopt Device Manager Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39039 - Too many devices imported at a time.
-39042 - Invalid device information in the imported file.
-39043 - Importing... Please wait.
-53125 - The Add Devices function has been locked due to too many invalid attempts.

unbindDeviceBySn

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/sn-unbind

Batch unbind devices by SN

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema UnbindDeviceSnOpenApiVO

Field	Type	Required	Description
sns	array<string>	yes	Unbind device serial number list, serial number should contains 13 characters.

// omada_call_operation
{
  "operationId": "unbindDeviceBySn",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch unbind devices by SN.
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

manuallyUpgrade

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/start-manually-upgrade

Start manually upgrade

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema UpgradeRequest

Field	Type	Required	Description
macs	array<string>	no	MAC list of devices
fileId	string	no	Firmware ID for upgrade

// omada_call_operation
{
  "operationId": "manuallyUpgrade",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Manually upgrade the devices of the same model in the site. The firmware needs to be uploaded first. Note: Each site can only execute one multi-device upgrade task at a time, and there is a number limit of the tasks that can be executed simultaneously in the controller.
The interface requires one of the permissions:
Site Manual Firmware Upgrade Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39020 - Failed to upgrade because no device is ready for upgrading.
-39050 - This device does not exist.
-43704 - The file has expired.

onlineRollingUpgrade

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/start-rolling-upgrade

Start batch rolling upgrade

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema RollingUpgradeRequest

Field	Type	Required	Description
macs	array<string>	no	MAC list of devices. E.g. AA-BB-CC-DD-11-22

// omada_call_operation
{
  "operationId": "onlineRollingUpgrade",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch online upgrade the devices in a certain order in the site. It is suggested to check firmware update before the operation, or the firmware might not be the latest
The interface requires one of the permissions:
Site Device Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-39020 - Failed to upgrade because no device is ready for upgrading.

updateDeviceTag

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/tag

Set device tag for given devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SetTagOpenApiVO

Field	Type	Required	Description
macs	array<string>	no	Device MAC list, like AA-BB-CC-DD-EE-FF
tagIds	array<string>	yes	Tag ID list

// omada_call_operation
{
  "operationId": "updateDeviceTag",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Set device tag for given devices.
The interface requires one of the permissions:
Site Device Manager Modify

unbindDevice

POST /openapi/v1/{omadacId}/sites/{siteId}/multi-devices/unbind

Batch unbind devices

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema UnbindDeviceOpenApiVO

Field	Type	Required	Description
deviceMacs	array<string>	yes	Unbind device mac list, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "unbindDevice",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch unbind devices.
The interface requires one of the permissions:
Site Bind/Unbind License Manager Modify

getAutoSelectDevices

POST /openapi/v1/{omadacId}/sites/{siteId}/quick-action/network-wizard/auto-select-devices

Get auto select devices in quick-config page.

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema QueryDeviceListOpenApiVO

Field	Type	Required	Description
macs	array<string>	yes	The device MAC address list.

// omada_call_operation
{
  "operationId": "getAutoSelectDevices",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Get auto select devices in quick-config page.
The interface requires one of the permissions:
Site Home View Only
Site Dashboard Manager View Only

getMspAdoptTip

GET /openapi/v1/msp/{mspId}/adopt-tip

MSP get adopt tip

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)

// omada_call_operation
{
  "operationId": "getMspAdoptTip"
}

Details, permissions and error codes

MSP get adopt tip
The interface requires one of the permissions:
MSP Adopt Device Manager Access
MSP Add Device Manager Access

exportMspAddFailDevices

GET /openapi/v1/msp/{mspId}/customers/{customerId}/devices/add/{operateId}/export

Export the device file that failed to add in MSP view.

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)
customerId	path	string	yes	Customer ID
operateId	path	string	yes	Operation ID
format	query	integer	yes	File format. 0: CSV, 1: XLSX

// omada_call_operation
{
  "operationId": "exportMspAddFailDevices",
  "params": {
    "customerId": "<customerId>",
    "operateId": "<operateId>",
    "format": "<format>"
  }
}

Details, permissions and error codes

Export the device file that failed to add in MSP view. Format should be a value as follows. 0 means CSV , 1 means XLSX.
The interface requires one of the permissions:
MSP Add Device Manager Access
MSP Add Device Manager Access

retryAddDeviceByMsp

POST /openapi/v1/msp/{mspId}/customers/{customerId}/sites/{siteId}/devices/{deviceMac}/add/retry

retry add device in msp view

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)
customerId	path	string	yes	Omada ID
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

Request body — application/json (required) — schema RetryAddDeviceOpenApiVO

Field	Type	Required	Description
username	string	no	retry add device username
password	string	no	retry add device password

// omada_call_operation
{
  "operationId": "retryAddDeviceByMsp",
  "params": {
    "customerId": "<customerId>",
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  },
  "body": "{...}"
}

Details, permissions and error codes

retry add device in msp view
The interface requires one of the permissions:
MSP Adopt Device Manager Access
MSP Add Device Manager Access

forgetDeviceForMsp

POST /openapi/v1/msp/{mspId}/customers/{customerId}/sites/{siteId}/devices/{deviceMac}/forget

Forget one device in MSP view.

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)
customerId	path	string	yes	Customer ID
siteId	path	string	yes	Site ID (site ID or site name)
deviceMac	path	string	yes	Device MAC address, like AA-BB-CC-DD-EE-FF

// omada_call_operation
{
  "operationId": "forgetDeviceForMsp",
  "params": {
    "customerId": "<customerId>",
    "siteId": "<siteId>",
    "deviceMac": "<deviceMac>"
  }
}

Details, permissions and error codes

Forget one device in MSP view.
The interface requires one of the permissions:
MSP Device Manager Modify

addDevicesForMsp

POST /openapi/v1/msp/{mspId}/customers/{customerId}/sites/{siteId}/devices/multi-add

Batch add devices in MSP view

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)
customerId	path	string	yes	Omada ID
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema MspAddDeviceListOpenApiVO

Field	Type	Required	Description
devices	array<AddDeviceVO>	yes	Add devices list
keepResult	boolean	no	Save the last result
allowOffline	boolean	no	Whether to allow offline addition. The default value is False
verifyCode	string	no
addType	integer	no	0/null indicates SN, and 1 indicates deviceKey
mspId	string	no	MSP ID

// omada_call_operation
{
  "operationId": "addDevicesForMsp",
  "params": {
    "customerId": "<customerId>",
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Batch add devices in MSP view.
The interface requires one of the permissions:
MSP Add Device Manager Access
MSP Add Device Manager Access

getAdoptAbleDevicesForMspBatchAdopt

GET /openapi/v1/msp/{mspId}/devices/batch/info

Batch get info of adopted device in MSP view.

Parameter	In	Type	Required	Description
mspId	path	string	auto	MSP ID (filled in automatically)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.name	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.status	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.ip	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
searchKey	query	string	no	Fuzzy query parameters, support field name,mac,ip
filters.tag	query	string	no	Filter query parameters, support field tag name

// omada_call_operation
{
  "operationId": "getAdoptAbleDevicesForMspBatchAdopt"
}

Details, permissions and error codes

Batch get info of adopted device in MSP view.
The interface requires one of the permissions:
MSP Adopt Device Manager Access
MSP Add Device Manager Access