{"components": {"securitySchemes": {"site-manager-api-key": {"in": "header", "name": "X-API-Key", "type": "apiKey"}}}, "info": {"title": "UniFi Site Manager API", "version": "1.0.0"}, "openapi": "3.0.3", "paths": {"/v1/devices": {"get": {"description": "Retrieves a list of UniFi devices managed by hosts where the UI account making the API call is the owner or a super admin. <br/><br/>**Note**: The structure of the `devices.uidb` field may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.", "operationId": "listDevices", "parameters": [{"description": "List of host IDs to filter the results", "example": ["900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321"], "in": "query", "name": "hostIds[]", "schema": {"items": {"type": "string"}, "type": "array"}}, {"description": "Last processed timestamp of devices in RFC3339 format", "example": "2026-03-12T10:42:00Z", "in": "query", "name": "time", "schema": {"type": "string"}}, {"description": "Number of items to return per page", "example": "10", "in": "query", "name": "pageSize", "schema": {"type": "string"}}, {"description": "Token for pagination to retrieve the next set of results", "example": "602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514", "in": "query", "name": "nextToken", "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": [{"hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "hostName": "unifi.yourdomain.com", "devices": [{"id": "F4E2C6C23F13", "mac": "F4E2C6C23F13", "name": "unifi.yourdomain.com", "model": "UDM SE", "shortname": "UDMPROSE", "ip": "192.168.1.226", "productLine": "network", "status": "online", "version": "4.1.13", "firmwareStatus": "upToDate", "updateAvailable": null, "isConsole": true, "isManaged": true, "startupTime": "2024-06-19T13:41:43Z", "adoptionTime": null, "note": null, "uidb": {"guid": "0fd8c390-a0e8-4cb2-b93a-7b3051c83c46", "id": "e85485da-54c3-4906-8f19-3cef4116ff02", "images": {"default": "3008400039c483c496f4ad820242c447", "nopadding": "67b553529d0e523ca9dd4826076c5f3f", "topology": "8371ecdda1f00f1636a2eefadf0d7d47"}}}], "updatedAt": "2026-03-12T10:42:00Z"}], "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d", "nextToken": "ba8e384e-3308-4236-b344-7357657351ca"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "data": {"description": "Generic response data, specific schema depends on the endpoint", "items": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"hostId": {"description": "Unique identifier of the host device", "type": "string"}, "hostName": {"description": "Name of the host device", "type": "string"}, "devices": {"description": "Array of devices managed by this host", "items": {"description": "Array of devices managed by this host", "nullable": true, "properties": {"id": {"description": "Unique identifier of the device", "type": "string"}, "mac": {"description": "MAC address of the device", "type": "string"}, "name": {"description": "User-defined name of the device", "type": "string"}, "model": {"description": "Model name of the device", "type": "string"}, "shortname": {"description": "Short identifier of the device model (e.g., UDMPROSE)", "type": "string"}, "ip": {"description": "IP address of the device", "type": "string"}, "productLine": {"description": "Product line of the device (network, protect, etc.)", "nullable": true, "type": "string"}, "status": {"description": "Current connection status of the device (online, offline, etc.)", "type": "string"}, "version": {"description": "Current firmware version of the device", "type": "string"}, "firmwareStatus": {"description": "Status of device firmware (upToDate, updateAvailable, etc.)", "type": "string"}, "updateAvailable": {"description": "Version of firmware update available for the device, if any", "nullable": true, "type": "string"}, "isConsole": {"description": "Indicates if the device is a console device", "nullable": true, "type": "boolean"}, "isManaged": {"description": "Indicates if the device is managed by the controller", "nullable": true, "type": "boolean"}, "startupTime": {"description": "Time when the device was last started in RFC3339 format", "format": "date-time", "nullable": true, "type": "string"}, "adoptionTime": {"description": "Time when the device was adopted in RFC3339 format", "nullable": true, "type": "string"}, "note": {"description": "User-defined notes for the device", "nullable": true, "type": "string"}, "uidb": {"description": "UI-specific metadata including images and identifiers"}}, "type": "object", "x-properties-order": ["id", "mac", "name", "model", "shortname", "ip", "productLine", "status", "version", "firmwareStatus", "updateAvailable", "isConsole", "isManaged", "startupTime", "adoptionTime", "note", "uidb"]}, "type": "array"}, "updatedAt": {"description": "Last update time in RFC3339 format", "format": "date-time", "type": "string"}}, "type": "object", "x-properties-order": ["hostId", "hostName", "devices", "updatedAt"]}, "type": "array"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}, "nextToken": {"description": "Pagination token for fetching the next set of results", "type": "string"}}, "type": "object", "x-properties-order": ["code", "data", "httpStatusCode", "traceId", "nextToken"]}}}, "description": "200"}, "400": {"content": {"application/json": {"examples": {"invalid parameter": {"value": {"code": "parameter_invalid", "httpStatusCode": 400, "message": "invalid time format: 2024-04-24", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "400"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to list devices": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to list devices", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "List Devices", "x-position": 4}}, "/v1/hosts": {"get": {"description": "Retrieves a list of all hosts associated with the UI account making the API call. <br/><br/>**Note**: The structure of `userData` and `reportedState` fields may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.", "operationId": "listHosts", "parameters": [{"description": "Number of items to return per page", "example": "10", "in": "query", "name": "pageSize", "schema": {"type": "string"}}, {"description": "Token for pagination to retrieve the next set of results", "example": "602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514", "in": "query", "name": "nextToken", "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": [{"id": "70A7419783ED0000000006797F060000000006C719490000000062ABD4EA:1261206302", "hardwareId": "e5bf13cd-98a7-5a96-9463-0d65d78cd3a4", "type": "ucore", "ipAddress": "220.130.137.169", "owner": true, "isBlocked": false, "registrationTime": "", "lastConnectionStateChange": "2024-04-16T02:52:54.193Z", "latestBackupTime": "", "userData": {"apps": ["users"], "consoleGroupMembers": [{"mac": "70A7419783ED", "role": "UNADOPTED", "roleAttributes": {"applications": {"access": {"owned": false, "required": false, "supported": true}, "connect": {"owned": false, "required": false, "supported": true}, "innerspace": {"owned": false, "required": false, "supported": true}, "network": {"owned": false, "required": true, "supported": true}, "protect": {"owned": false, "required": false, "supported": true}, "talk": {"owned": false, "required": false, "supported": true}}, "candidateRoles": ["PRIMARY"], "connectedState": "CONNECTED", "connectedStateLastChanged": "2024-04-16T02:52:54.193Z"}, "sysId": 59925}], "controllers": ["network", "protect", "access", "talk", "connect", "innerspace"], "email": "example@ui.com", "features": {"deviceGroups": true, "floorplan": {"canEdit": true, "canView": true}, "manageApplications": true, "notifications": true, "pion": true, "webrtc": {"iceRestart": true, "mediaStreams": true, "twoWayAudio": true}}, "fullName": "UniFi User", "localId": "d4eb483d-98a7-438b-abe1-f46628dff73f", "permissions": {"access.management": ["admin"], "connect.management": ["admin"], "innerspace.management": ["admin"], "network.management": ["admin"], "protect.management": ["admin"], "system.management.location": ["admin"], "system.management.user": ["admin"], "talk.management": ["admin"]}, "role": "owner", "roleId": "c349b256-98a7-44ab-b8a1-13c437ea7742", "status": "ACTIVE"}, "reportedState": null}], "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d", "nextToken": "ba8e384e-3308-4236-b344-7357657351ca"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "data": {"description": "Generic response data, specific schema depends on the endpoint", "items": {"description": "Generic response data, specific schema depends on the endpoint", "properties": {"id": {"description": "Unique identifier of the host device", "type": "string"}, "hardwareId": {"description": "Hardware identifier of the device", "type": "string"}, "type": {"description": "Type of the device (console, network-server)", "type": "string"}, "ipAddress": {"description": "Current IP address of the device", "type": "string"}, "owner": {"description": "Indicates if the current user is the owner of this device", "type": "boolean"}, "isBlocked": {"description": "Indicates if the device is blocked from cloud access", "type": "boolean"}, "registrationTime": {"description": "Time in RFC3339 format when the device was registered to the cloud", "format": "date-time", "type": "string"}, "lastConnectionStateChange": {"description": "Time in RFC3339 format when the connection state last changed", "format": "date-time", "type": "string"}, "latestBackupTime": {"description": "Time in RFC3339 format of the latest device backup", "format": "date-time", "type": "string"}, "userData": {"description": "User-specific data associated with the device including permissions and role information"}, "reportedState": {"description": "Device's reported state information"}}, "type": "object", "x-properties-order": ["id", "hardwareId", "type", "ipAddress", "owner", "isBlocked", "registrationTime", "lastConnectionStateChange", "latestBackupTime", "userData", "reportedState"]}, "type": "array"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}, "nextToken": {"description": "Pagination token for fetching the next set of results", "type": "string"}}, "type": "object", "x-properties-order": ["code", "data", "httpStatusCode", "traceId", "nextToken"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to list hosts": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to list hosts", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "List Hosts", "x-position": 1}}, "/v1/hosts/{id}": {"get": {"description": "Retrieves detailed information about a specific host by ID. <br/><br/>**Note**: The structure of the `userData` and `reportedState` fields may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.", "operationId": "getHostByID", "parameters": [{"description": "Unique identifier of the host", "example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "in": "path", "name": "id", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"console": {"value": {"data": {"id": "70A7419783ED0000000006797F060000000006C719490000000062ABD4EA:1261206302", "hardwareId": "e5bf13cd-98a7-5a96-9463-0d65d78cd3a4", "type": "ucore", "ipAddress": "220.130.137.169", "owner": true, "isBlocked": false, "registrationTime": "", "lastConnectionStateChange": "2024-04-16T02:52:54.193Z", "latestBackupTime": "", "userData": {"apps": ["users"], "consoleGroupMembers": [{"mac": "70A7419783ED", "role": "UNADOPTED", "roleAttributes": {"applications": {"access": {"owned": false, "required": false, "supported": true}, "connect": {"owned": false, "required": false, "supported": true}, "innerspace": {"owned": false, "required": false, "supported": true}, "network": {"owned": false, "required": true, "supported": true}, "protect": {"owned": false, "required": false, "supported": true}, "talk": {"owned": false, "required": false, "supported": true}}, "candidateRoles": ["PRIMARY"], "connectedState": "CONNECTED", "connectedStateLastChanged": "2024-04-16T02:52:54.193Z"}, "sysId": 59925}], "controllers": ["network", "protect", "access", "talk", "connect", "innerspace"], "email": "example@ui.com", "features": {"deviceGroups": true, "floorplan": {"canEdit": true, "canView": true}, "manageApplications": true, "notifications": true, "pion": true, "webrtc": {"iceRestart": true, "mediaStreams": true, "twoWayAudio": true}}, "fullName": "UniFi User", "localId": "d4eb483d-98a7-438b-abe1-f46628dff73f", "permissions": {"access.management": ["admin"], "connect.management": ["admin"], "innerspace.management": ["admin"], "network.management": ["admin"], "protect.management": ["admin"], "system.management.location": ["admin"], "system.management.user": ["admin"], "talk.management": ["admin"]}, "role": "owner", "roleId": "c349b256-98a7-44ab-b8a1-13c437ea7742", "status": "ACTIVE"}, "reportedState": null}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}, "network-server": {"value": {"data": {"id": "1d9cf3ee-0c0f-466e-933c-9af829f09b50", "hardwareId": "b000b21e-0000-1111-add9-c1eed3897602", "type": "network-server", "ipAddress": "192.168.1.124", "owner": true, "isBlocked": false, "registrationTime": "2024-02-07T10:25:21.981Z", "lastConnectionStateChange": "2024-06-10T07:52:23.382Z", "latestBackupTime": "", "userData": null, "reportedState": {"controller_uuid": "b000b21e-0000-1111-add9-c1eed3897602", "deviceId": "1d9cf3ee-0c0f-466e-933c-9af829f09b50", "firmware_version": null, "hardware_id": "b000b21e-0000-1111-add9-c1eed3897602", "host_type": 0, "hostname": "example-domain.ui.com", "inform_port": 8080, "ipAddrs": ["192.168.1.124"], "mgmt_port": 8443, "name": "Self-Hosted Site", "override_inform_host": false, "release_channel": "release", "state": "connected", "version": "8.3.11"}}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "properties": {"id": {"description": "Unique identifier of the host device", "type": "string"}, "hardwareId": {"description": "Hardware identifier of the device", "type": "string"}, "type": {"description": "Type of the device (console, network-server)", "type": "string"}, "ipAddress": {"description": "Current IP address of the device", "type": "string"}, "owner": {"description": "Indicates if the current user is the owner of this device", "type": "boolean"}, "isBlocked": {"description": "Indicates if the device is blocked from cloud access", "type": "boolean"}, "registrationTime": {"description": "Time in RFC3339 format when the device was registered to the cloud", "format": "date-time", "type": "string"}, "lastConnectionStateChange": {"description": "Time in RFC3339 format when the connection state last changed", "format": "date-time", "type": "string"}, "latestBackupTime": {"description": "Time in RFC3339 format of the latest device backup", "format": "date-time", "type": "string"}, "userData": {"description": "User-specific data associated with the device including permissions and role information"}, "reportedState": {"description": "Device's reported state information"}}, "type": "object", "x-properties-order": ["id", "hardwareId", "type", "ipAddress", "owner", "isBlocked", "registrationTime", "lastConnectionStateChange", "latestBackupTime", "userData", "reportedState"]}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "404": {"content": {"application/json": {"examples": {"not found": {"value": {"code": "NOT_FOUND", "httpStatusCode": 404, "message": "thing not found: 942A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "404"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to get host": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to get host", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "Get Host by ID", "x-position": 2}}, "/v1/isp-metrics/{type}": {"get": {"description": "Retrieves ISP metrics data for all sites linked to the UI account's API key. 5-minute interval metrics are available for at least 24 hours, and 1-hour interval metrics are available for at least 30 days.", "operationId": "getISPMetrics", "parameters": [{"description": "Specifies whether metrics are returned using `5m` or `1h` intervals", "example": "5m", "in": "path", "name": "type", "required": true, "schema": {"type": "string"}}, {"description": "The earliest timestamp to retrieve data from (RFC3339 format)", "example": "2024-06-30T13:35:00Z", "in": "query", "name": "beginTimestamp", "schema": {"type": "string"}}, {"description": "The latest timestamp to retrieve data up to (RFC3339 format)", "example": "2024-06-30T15:35:00Z", "in": "query", "name": "endTimestamp", "schema": {"type": "string"}}, {"description": "Specifies the time range of metrics to retrieve, starting from when the request is made. Supports `24h` for 5-minute metrics, and `7d` or `30d` for 1-hour metrics. This parameter **cannot** be used with `beginTimestamp` or `endTimestamp`.", "in": "query", "name": "duration", "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": [{"metricType": "5m", "periods": [{"data": {"wan": {"avgLatency": 1, "download_kbps": 0, "downtime": 0, "ispAsn": "12578", "ispName": "ISP", "maxLatency": 2, "packetLoss": 0, "upload_kbps": 0, "uptime": 100}}, "metricTime": "2024-06-30T13:35:00Z", "version": "1"}], "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "siteId": "661900ae6aec8f548d49fd54"}], "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "items": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"metricType": {"type": "string"}, "periods": {"items": {"nullable": true, "properties": {"data": {"properties": {"wan": {"properties": {"avgLatency": {"type": "integer"}, "download_kbps": {"type": "integer"}, "downtime": {"type": "integer"}, "ispAsn": {"type": "string"}, "ispName": {"type": "string"}, "maxLatency": {"type": "integer"}, "packetLoss": {"type": "integer"}, "upload_kbps": {"type": "integer"}, "uptime": {"type": "integer"}}, "type": "object", "x-properties-order": ["avgLatency", "download_kbps", "downtime", "ispAsn", "ispName", "maxLatency", "packetLoss", "upload_kbps", "uptime"]}}, "type": "object", "x-properties-order": ["wan"]}, "metricTime": {"format": "date-time", "type": "string"}, "version": {"type": "string"}}, "type": "object", "x-properties-order": ["data", "metricTime", "version"]}, "type": "array"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}}, "type": "object", "x-properties-order": ["metricType", "periods", "hostId", "siteId"]}, "type": "array"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "400": {"content": {"application/json": {"examples": {"invalid parameter": {"value": {"code": "parameter_invalid", "httpStatusCode": 400, "message": "invalid beginTimestamp format: 2024-06-30", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "400"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to get ISP metrics": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to get ISP metrics", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "Get ISP Metrics", "x-position": 5}}, "/v1/isp-metrics/{type}/query": {"post": {"description": "Retrieves ISP metrics data based on specific query parameters. 5-minute interval metrics are available for at least 24 hours, and 1-hour interval metrics are available for at least 30 days. <br/><br/>**Note:** If the UI account lacks access to all requested sites, a 502 error is returned. If partial access is granted, the response will include `status: partialSuccess`.", "operationId": "queryISPMetrics", "parameters": [{"description": "Specifies whether metrics are returned using `5m` or `1h` intervals", "example": "5m", "in": "path", "name": "type", "required": true, "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"example": {"sites": [{"beginTimestamp": "2024-06-30T13:35:00Z", "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "endTimestamp": "2024-06-30T15:35:00Z", "siteId": "661900ae6aec8f548d49fd54"}]}, "schema": {"properties": {"sites": {"items": {"nullable": true, "properties": {"beginTimestamp": {"format": "date-time", "type": "string"}, "hostId": {"type": "string"}, "endTimestamp": {"format": "date-time", "type": "string"}, "siteId": {"type": "string"}}, "required": ["hostId", "siteId"], "type": "object", "x-properties-order": ["beginTimestamp", "hostId", "endTimestamp", "siteId"]}, "required": ["hostId", "siteId"], "type": "array"}}, "type": "object", "x-properties-order": ["sites"]}}}}, "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": {"metrics": [{"metricType": "5m", "periods": [{"data": {"wan": {"avgLatency": 1, "download_kbps": 0, "downtime": 0, "ispAsn": "12578", "ispName": "ISP", "maxLatency": 2, "packetLoss": 0, "upload_kbps": 0, "uptime": 100}}, "metricTime": "2024-06-30T13:35:00Z", "version": "1"}], "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "siteId": "661900ae6aec8f548d49fd54"}]}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}, "partial success": {"value": {"data": {"metrics": [{"metricType": "5m", "periods": [{"data": {"wan": {"avgLatency": 1, "download_kbps": 0, "downtime": 0, "ispAsn": "12578", "ispName": "ISP", "maxLatency": 2, "packetLoss": 0, "upload_kbps": 0, "uptime": 100}}, "metricTime": "2024-06-30T13:35:00Z", "version": "1"}], "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "siteId": "661900ae6aec8f548d49fd54"}], "message": "some of the requested sites are not accessible for the user or were ignored as duplicates", "status": "partialSuccess"}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"metrics": {"items": {"nullable": true, "properties": {"metricType": {"type": "string"}, "periods": {"items": {"nullable": true, "properties": {"data": {"properties": {"wan": {"properties": {"avgLatency": {"type": "integer"}, "download_kbps": {"type": "integer"}, "downtime": {"type": "integer"}, "ispAsn": {"type": "string"}, "ispName": {"type": "string"}, "maxLatency": {"type": "integer"}, "packetLoss": {"type": "integer"}, "upload_kbps": {"type": "integer"}, "uptime": {"type": "integer"}}, "type": "object", "x-properties-order": ["avgLatency", "download_kbps", "downtime", "ispAsn", "ispName", "maxLatency", "packetLoss", "upload_kbps", "uptime"]}}, "type": "object", "x-properties-order": ["wan"]}, "metricTime": {"format": "date-time", "type": "string"}, "version": {"type": "string"}}, "type": "object", "x-properties-order": ["data", "metricTime", "version"]}, "type": "array"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}}, "type": "object", "x-properties-order": ["metricType", "periods", "hostId", "siteId"]}, "type": "array"}, "message": {"nullable": true, "type": "string"}, "status": {"nullable": true, "type": "string"}}, "type": "object", "x-properties-order": ["metrics", "message", "status"]}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "400": {"content": {"application/json": {"examples": {"invalid parameter": {"value": {"code": "parameter_invalid", "httpStatusCode": 400, "message": "invalid beginTimestamp format: 2024-06-30", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "400"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to query ISP metrics": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to query ISP metrics", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "Query ISP Metrics", "x-position": 6}}, "/v1/sd-wan-configs": {"get": {"description": "Retrieves a list of all SD-WAN configurations associated with the UI account making the API call.", "operationId": "listSDWanConfigs", "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": [{"id": "9304163b-680d-4de8-a7a0-7617e328911d", "name": "SD-WAN test", "type": "sdwan-hbsp"}], "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "items": {"description": "Generic response data, specific schema depends on the endpoint", "properties": {"id": {"description": "Unique identifier of the SD-WAN config", "type": "string"}, "name": {"description": "Name of the SD-WAN config", "type": "string"}, "type": {"description": "Type of SD-WAN config - Currently only supports sdwan-hbsp", "enum": [["sdwan-hbsp"]], "type": "string"}}, "type": "object", "x-properties-order": ["id", "name", "type"]}, "type": "array"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to list network cloud SD-WAN configs": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to list network cloud SD-WAN configs", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "List SD-WAN Configs", "x-position": 7}}, "/v1/sd-wan-configs/{id}": {"get": {"description": "Retrieves detailed information about a specific SD-WAN configuration by ID.", "operationId": "getSDWanConfigByID", "parameters": [{"description": "Unique identifier of the SD-WAN configuration", "example": "9304163b-680d-4de8-a7a0-7617e328911d", "in": "path", "name": "id", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": {"id": "b344034f-2636-478c-8c7a-e3350f8ed37a", "name": "RS test", "type": "sdwan-hbsp", "variant": "single", "settings": {"hubsInterconnect": null, "spokeToHubTunnelsMode": "scalable", "spokesAutoScaleAndNatEnabled": true, "spokesAutoScaleAndNatRange": "172.16.0.0/12", "spokesIsolate": true, "spokeStandardSettingsEnabled": false, "spokeStandardSettingsValues": null, "spokeToHubRouting": "geo"}, "hubs": [{"id": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894_670d14b2b4e979611b761866", "hostId": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894", "siteId": "670d14b2b4e979611b761866", "networkIds": ["670d14deb4e979611b761880"], "routes": [], "primaryWan": "WAN", "wanFailover": false}], "spokes": [{"id": "28704E43D00C0000000008339D3C0000000008A2F4D300000000669FE9E7:1731456649_670d153bf6db0d4204f8d150", "hostId": "28704E43D00C0000000008339D3C0000000008A2F4D300000000669FE9E7:1731456649", "siteId": "670d153bf6db0d4204f8d150", "networkIds": [], "routes": ["172.16.1.0/24"], "primaryWan": "WAN", "wanFailover": false, "hubsPriority": null}, {"id": "F4E2C61FA6000000000007D5831A00000000083CEEC600000000655DA309:763649230_66b5f02af5521234f6f28a23", "hostId": "F4E2C61FA6000000000007D5831A00000000083CEEC600000000655DA309:763649230", "siteId": "66b5f02af5521234f6f28a23", "networkIds": [], "routes": ["172.16.2.0/24"], "primaryWan": "WAN", "wanFailover": false, "hubsPriority": null}]}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"id": {"description": "Unique identifier of the SD-WAN config", "type": "string"}, "name": {"description": "Name of the SD-WAN config", "type": "string"}, "type": {"description": "Type of SD-WAN config - Currently only supports sdwan-hbsp", "enum": [["sdwan-hbsp"]], "type": "string"}, "variant": {"description": "Variant of SD-WAN configuration", "enum": [["distributed", "failover", "single"]], "type": "string"}, "settings": {"description": "Advanced settings", "properties": {"hubsInterconnect": {"nullable": true, "type": "boolean"}, "spokeToHubTunnelsMode": {"enum": [["maxResiliency", "redundant", "scalable"]], "type": "string"}, "spokesAutoScaleAndNatEnabled": {"description": "Auto-assigns subnet and routes; otherwise, users enter them manually.", "type": "boolean"}, "spokesAutoScaleAndNatRange": {"description": "Subnet in CIDR format, Example: 172.16.0.0/12", "nullable": true, "type": "string"}, "spokesIsolate": {"description": "Setting for NET: Spokes can reach hubs but not other spokes.", "type": "boolean"}, "spokeStandardSettingsEnabled": {"description": "Enable spoke standard settings", "type": "boolean"}, "spokeStandardSettingsValues": {"description": "Spoke standard settings", "nullable": true, "properties": {"primaryWan": {"description": "Example: 'WAN'", "nullable": true, "type": "string"}, "wanFailover": {"description": "Use fail over WAN.", "nullable": true, "type": "boolean"}}, "type": "object", "x-properties-order": ["primaryWan", "wanFailover"]}, "spokeToHubRouting": {"enum": [["custom", "geo"]], "nullable": true, "type": "string"}}, "type": "object", "x-properties-order": ["hubsInterconnect", "spokeToHubTunnelsMode", "spokesAutoScaleAndNatEnabled", "spokesAutoScaleAndNatRange", "spokesIsolate", "spokeStandardSettingsEnabled", "spokeStandardSettingsValues", "spokeToHubRouting"]}, "hubs": {"items": {"properties": {"id": {"type": "string"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}, "networkIds": {"description": "Ids of networks belonging to the hub", "items": {"description": "Ids of networks belonging to the hub", "type": "string"}, "type": "array"}, "routes": {"description": "Subnets in CIDR format: 10.0.0.0/24", "items": {"description": "Subnets in CIDR format: 10.0.0.0/24", "type": "string"}, "type": "array"}, "primaryWan": {"description": "Example: 'WAN'", "type": "string"}, "wanFailover": {"description": "Use fail over WAN.", "type": "boolean"}}, "type": "object", "x-properties-order": ["id", "hostId", "siteId", "networkIds", "routes", "primaryWan", "wanFailover"]}, "type": "array"}, "spokes": {"items": {"properties": {"id": {"type": "string"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}, "networkIds": {"description": "Ids of networks belonging to the spoke", "items": {"description": "Ids of networks belonging to the spoke", "type": "string"}, "type": "array"}, "routes": {"description": "Subnets in CIDR format: 10.0.0.0/24", "items": {"description": "Subnets in CIDR format: 10.0.0.0/24", "type": "string"}, "type": "array"}, "primaryWan": {"description": "Example: 'WAN'", "type": "string"}, "wanFailover": {"description": "Use fail over WAN.", "type": "boolean"}, "hubsPriority": {"description": "Non-null for distributed topology and spokeToHubRouting=custom", "items": {"description": "Non-null for distributed topology and spokeToHubRouting=custom", "type": "string"}, "type": "array"}}, "type": "object", "x-properties-order": ["id", "hostId", "siteId", "networkIds", "routes", "primaryWan", "wanFailover", "hubsPriority"]}, "type": "array"}}, "type": "object", "x-properties-order": ["id", "name", "type", "variant", "settings", "hubs", "spokes"]}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "404": {"content": {"application/json": {"examples": {"config not found": {"value": {"code": "not_found", "httpStatusCode": 404, "message": "config not found", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "404"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to get network cloud SD-WAN config by ID": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to get network cloud SD-WAN config by ID", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "Get SD-WAN Config by ID", "x-position": 8}}, "/v1/sd-wan-configs/{id}/status": {"get": {"description": "Retrieves the status of a specific SD-WAN configuration, including deployment progress, errors, and associated hubs.", "operationId": "getSDWanConfigStatus", "parameters": [{"description": "Unique identifier of the SD-WAN configuration", "example": "9304163b-680d-4de8-a7a0-7617e328911d", "in": "path", "name": "id", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": {"id": "", "fingerprint": "85d521a1b3c8992f", "updatedAt": 1739454923342, "hubs": [{"id": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894_670d14b2b4e979611b761866", "hostId": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894", "siteId": "670d14b2b4e979611b761866", "name": "Marlind's UDM SE", "primaryWanStatus": {"ip": "194.22.30.166", "latency": 1, "internetIssues": [], "wanId": "WAN"}, "secondaryWanStatus": {"ip": "", "latency": null, "internetIssues": null, "wanId": ""}, "errors": [], "warnings": [], "numberOfTunnelsUsedByOtherFeatures": 0, "networks": [{"networkId": "670d14deb4e979611b761880", "name": "Default", "errors": [], "warnings": []}], "routes": [], "applyStatus": "OK"}], "spokes": [{"id": "28704E43D00C0000000008339D3C0000000008A2F4D300000000669FE9E7:1731456649_670d153bf6db0d4204f8d150", "hostId": "28704E43D00C0000000008339D3C0000000008A2F4D300000000669FE9E7:1731456649", "siteId": "670d153bf6db0d4204f8d150", "name": "Marlind's UDR", "primaryWanStatus": {"ip": "10.0.1.142", "latency": 1, "internetIssues": [], "wanId": "WAN"}, "secondaryWanStatus": {"ip": "", "latency": null, "internetIssues": null, "wanId": ""}, "errors": [], "warnings": [], "numberOfTunnelsUsedByOtherFeatures": 0, "networks": [], "routes": [{"routeValue": "172.16.1.0/24", "errors": [], "warnings": []}], "connections": [{"hubId": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894_670d14b2b4e979611b761866", "tunnels": [{"spokeWanId": "WAN", "hubWanId": "WAN", "status": "connected"}]}], "applyStatus": "OK"}, {"id": "F4E2C61FA6000000000007D5831A00000000083CEEC600000000655DA309:763649230_66b5f02af5521234f6f28a23", "hostId": "F4E2C61FA6000000000007D5831A00000000083CEEC600000000655DA309:763649230", "siteId": "66b5f02af5521234f6f28a23", "name": "AG UCG Ultra STG", "primaryWanStatus": {"ip": "10.35.87.53", "latency": 2, "internetIssues": [], "wanId": "WAN"}, "secondaryWanStatus": {"ip": "", "latency": null, "internetIssues": null, "wanId": ""}, "errors": [], "warnings": [], "numberOfTunnelsUsedByOtherFeatures": 0, "networks": [], "routes": [{"routeValue": "172.16.2.0/24", "errors": [], "warnings": []}], "connections": [{"hubId": "9C05D6B1DA7100000000080A820B000000000877B4A4000000006634E113:779231894_670d14b2b4e979611b761866", "tunnels": [{"spokeWanId": "WAN", "hubWanId": "WAN", "status": "connected"}]}], "applyStatus": "OK"}], "lastGeneratedAt": 1739454923342, "generateStatus": "OK", "errors": [], "warnings": []}, "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"data": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"id": {"description": "Unique identifier of the SD-WAN configuration", "type": "string"}, "fingerprint": {"description": "A unique identifier representing the current state of the configuration.", "type": "string"}, "updatedAt": {"description": "The timestamp of the last update to the SD-WAN configuration.", "format": "int64", "type": "integer"}, "hubs": {"description": "List of hubs in SD-WAN configuration", "items": {"description": "List of hubs in SD-WAN configuration", "properties": {"id": {"description": "Unique identifier of the hub", "type": "string"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}, "name": {"type": "string"}, "primaryWanStatus": {"properties": {"ip": {"description": "IP format: 10.0.0.1", "type": "string"}, "latency": {"format": "double", "nullable": true, "type": "number"}, "internetIssues": {"description": "If WAN experience issues", "items": {"additionalProperties": {"description": "If WAN experience issues"}, "description": "If WAN experience issues", "type": "object"}, "type": "array"}, "wanId": {"type": "string"}}, "type": "object", "x-properties-order": ["ip", "latency", "internetIssues", "wanId"]}, "secondaryWanStatus": {"properties": {"ip": {"description": "IP format: 10.0.0.1", "type": "string"}, "latency": {"format": "double", "nullable": true, "type": "number"}, "internetIssues": {"description": "If WAN experience issues", "items": {"additionalProperties": {"description": "If WAN experience issues"}, "description": "If WAN experience issues", "type": "object"}, "type": "array"}, "wanId": {"type": "string"}}, "type": "object", "x-properties-order": ["ip", "latency", "internetIssues", "wanId"]}, "errors": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "warnings": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "numberOfTunnelsUsedByOtherFeatures": {"type": "integer"}, "networks": {"items": {"properties": {"networkId": {"type": "string"}, "name": {"type": "string"}, "errors": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "warnings": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}}, "type": "object", "x-properties-order": ["networkId", "name", "errors", "warnings"]}, "type": "array"}, "routes": {"items": {"properties": {"routeValue": {"description": "subnet in CIDR format: 10.0.0.0/24", "type": "string"}, "errors": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "warnings": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}}, "type": "object", "x-properties-order": ["routeValue", "errors", "warnings"]}, "type": "array"}, "applyStatus": {"description": "The current status of the hub configuration application.", "enum": [["ok", "creating", "updating", "removing", "createFailed", "updateFailed", "removeFailed"]], "type": "string"}}, "type": "object", "x-properties-order": ["id", "hostId", "siteId", "name", "primaryWanStatus", "secondaryWanStatus", "errors", "warnings", "numberOfTunnelsUsedByOtherFeatures", "networks", "routes", "applyStatus"]}, "type": "array"}, "spokes": {"description": "A list of spokes associated with the SD-WAN config.", "items": {"description": "A list of spokes associated with the SD-WAN config.", "properties": {"id": {"type": "string"}, "hostId": {"type": "string"}, "siteId": {"type": "string"}, "name": {"type": "string"}, "primaryWanStatus": {"properties": {"ip": {"description": "IP format: 10.0.0.1", "type": "string"}, "latency": {"format": "double", "nullable": true, "type": "number"}, "internetIssues": {"description": "If WAN experience issues", "items": {"additionalProperties": {"description": "If WAN experience issues"}, "description": "If WAN experience issues", "type": "object"}, "type": "array"}, "wanId": {"type": "string"}}, "type": "object", "x-properties-order": ["ip", "latency", "internetIssues", "wanId"]}, "secondaryWanStatus": {"properties": {"ip": {"description": "IP format: 10.0.0.1", "type": "string"}, "latency": {"format": "double", "nullable": true, "type": "number"}, "internetIssues": {"description": "If WAN experience issues", "items": {"additionalProperties": {"description": "If WAN experience issues"}, "description": "If WAN experience issues", "type": "object"}, "type": "array"}, "wanId": {"type": "string"}}, "type": "object", "x-properties-order": ["ip", "latency", "internetIssues", "wanId"]}, "errors": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "warnings": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "numberOfTunnelsUsedByOtherFeatures": {"type": "integer"}, "networks": {"items": {"properties": {"networkId": {"type": "string"}, "name": {"type": "string"}, "errors": {"description": "A list of error messages related to the network, if any.", "items": {"additionalProperties": {"description": "A list of error messages related to the network, if any."}, "description": "A list of error messages related to the network, if any.", "type": "object"}, "type": "array"}, "warnings": {"description": "A list of warning messages related to the network, if any.", "items": {"additionalProperties": {"description": "A list of warning messages related to the network, if any."}, "description": "A list of warning messages related to the network, if any.", "type": "object"}, "type": "array"}}, "type": "object", "x-properties-order": ["networkId", "name", "errors", "warnings"]}, "type": "array"}, "routes": {"items": {"properties": {"routeValue": {"description": "subnet in CIDR format: 10.0.0.0/24", "type": "string"}, "errors": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}, "warnings": {"items": {"additionalProperties": {}, "type": "object"}, "type": "array"}}, "type": "object", "x-properties-order": ["routeValue", "errors", "warnings"]}, "type": "array"}, "connections": {"items": {"properties": {"hubId": {"type": "string"}, "tunnels": {"items": {"properties": {"spokeWanId": {"type": "string"}, "hubWanId": {"type": "string"}, "status": {"description": "The current status of the tunnel connection.", "enum": [["connected", "disconnected", "pending"]], "type": "string"}}, "type": "object", "x-properties-order": ["spokeWanId", "hubWanId", "status"]}, "type": "array"}}, "type": "object", "x-properties-order": ["hubId", "tunnels"]}, "type": "array"}, "applyStatus": {"description": "The current status of the hub configuration application.", "enum": [["ok", "creating", "updating", "removing", "createFailed", "updateFailed", "removeFailed"]], "type": "string"}}, "type": "object", "x-properties-order": ["id", "hostId", "siteId", "name", "primaryWanStatus", "secondaryWanStatus", "errors", "warnings", "numberOfTunnelsUsedByOtherFeatures", "networks", "routes", "connections", "applyStatus"]}, "type": "array"}, "lastGeneratedAt": {"description": "The timestamp of the last generation of the SD-WAN configuration.", "format": "int64", "type": "integer"}, "generateStatus": {"description": "The status of the configuration generation process.", "enum": [["OK", "GENERATING", "GENERATE_FAILED"]], "type": "string"}, "errors": {"description": "A list of error messages related to the configuration, if any.", "items": {"additionalProperties": {"description": "A list of error messages related to the configuration, if any."}, "description": "A list of error messages related to the configuration, if any.", "type": "object"}, "type": "array"}, "warnings": {"description": "A list of warning messages related to the configuration, if any.", "items": {"additionalProperties": {"description": "A list of warning messages related to the configuration, if any."}, "description": "A list of warning messages related to the configuration, if any.", "type": "object"}, "type": "array"}}, "type": "object", "x-properties-order": ["id", "fingerprint", "updatedAt", "hubs", "spokes", "lastGeneratedAt", "generateStatus", "errors", "warnings"]}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["data", "httpStatusCode", "traceId"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "404": {"content": {"application/json": {"examples": {"config not found": {"value": {"code": "not_found", "httpStatusCode": 404, "message": "config not found", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "404"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to get network cloud SD-WAN config status by ID": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to get network cloud SD-WAN config status by ID", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "Get SD-WAN Config Status", "x-position": 9}}, "/v1/sites": {"get": {"description": "Retrieves a list of all sites (from hosts running the UniFi Network application) associated with the UI account making the API call. <br/><br/>**Note**: The structure of the `meta` and `statistics` fields may vary depending on the UniFi Network version. The example provided is based on UniFi OS 4.1.13.", "operationId": "listSites", "parameters": [{"description": "Number of items to return per page", "example": "10", "in": "query", "name": "pageSize", "schema": {"type": "string"}}, {"description": "Token for pagination to retrieve the next set of results", "example": "602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514", "in": "query", "name": "nextToken", "schema": {"type": "string"}}], "responses": {"200": {"content": {"application/json": {"examples": {"ok": {"value": {"data": [{"siteId": "661de833b6b2463f0c20b319", "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789", "meta": {"desc": "Default", "gatewayMac": "70:a7:41:97:83:ed", "name": "default", "timezone": "Asia/Taipei"}, "statistics": {"counts": {"criticalNotification": 0, "gatewayDevice": 1, "guestClient": 0, "lanConfiguration": 1, "offlineDevice": 0, "offlineGatewayDevice": 0, "offlineWifiDevice": 0, "offlineWiredDevice": 0, "pendingUpdateDevice": 0, "totalDevice": 1, "wanConfiguration": 2, "wifiClient": 0, "wifiConfiguration": 0, "wifiDevice": 0, "wiredClient": 0, "wiredDevice": 0}, "gateway": {"hardwareId": "e5bf13cd-98a7-5a96-9463-0d65d78cd3a4", "inspectionState": "off", "ipsMode": "disabled", "ipsSignature": {"rulesCount": 53031, "type": "ET"}, "shortname": "UDMPRO"}, "internetIssues": [], "ispInfo": {"name": "Chunghwa Telecom", "organization": "Data Communication Business Group"}, "percentages": {"wanUptime": 100}}, "permission": "admin", "isOwner": true}], "httpStatusCode": 200, "traceId": "a7dc15e0eb4527142d7823515b15f87d", "nextToken": "ba8e384e-3308-4236-b344-7357657351ca"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "data": {"description": "Generic response data, specific schema depends on the endpoint", "items": {"description": "Generic response data, specific schema depends on the endpoint", "nullable": true, "properties": {"siteId": {"description": "Unique identifier of the site", "type": "string"}, "hostId": {"description": "Unique identifier of the host device managing this site", "type": "string"}, "meta": {"description": "Site metadata including name, description, timezone, and gateway MAC address. Structure may vary depending on the UniFi Network version"}, "statistics": {"description": "Site statistics including device counts, client counts, and network performance metrics. Structure may vary depending on the UniFi Network version"}, "permission": {"description": "Permission level of the current user for this site (admin, readonly, etc.)", "type": "string"}, "isOwner": {"description": "Indicates if the current user is the owner of this site", "type": "boolean"}}, "type": "object", "x-properties-order": ["siteId", "hostId", "meta", "statistics", "permission", "isOwner"]}, "type": "array"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "traceId": {"description": "Request trace identifier", "type": "string"}, "nextToken": {"description": "Pagination token for fetching the next set of results", "type": "string"}}, "type": "object", "x-properties-order": ["code", "data", "httpStatusCode", "traceId", "nextToken"]}}}, "description": "200"}, "401": {"content": {"application/json": {"examples": {"unauthorized": {"value": {"code": "unauthorized", "httpStatusCode": 401, "message": "unauthorized", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "401"}, "429": {"content": {"application/json": {"examples": {"rate limit": {"value": {"code": "rate_limit", "httpStatusCode": 429, "message": "rate limit exceeded, retry after 5.372786998s", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "429", "headers": {"Retry-After": {"example": "5", "schema": {"type": "string"}}}}, "500": {"content": {"application/json": {"examples": {"failed to list sites": {"value": {"code": "server_error", "httpStatusCode": 500, "message": "failed to list sites", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "500"}, "502": {"content": {"application/json": {"examples": {"bad gateway": {"value": {"code": "bad_gateway", "httpStatusCode": 502, "message": "bad gateway", "traceId": "a7dc15e0eb4527142d7823515b15f87d"}}}, "schema": {"properties": {"code": {"description": "Error code from upstream"}, "httpStatusCode": {"description": "HTTP status code", "type": "integer"}, "message": {"description": "Error message", "type": "string"}, "traceId": {"description": "Request trace identifier", "type": "string"}}, "type": "object", "x-properties-order": ["code", "httpStatusCode", "message", "traceId"]}}}, "description": "502"}}, "summary": "List Sites", "x-position": 3}}}, "security": [{"site-manager-api-key": []}], "servers": [{"url": "https://api.ui.com"}], "tags": [{"name": "cloud-connector", "x-displayName": "Connector"}]}