This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Site Manager API v1.0 (Official)

1 - Getting Started

A comprehensive guide for unifi.ui.com (Site Manager) users to utilize the API effectively

Getting Started

The Site Manager API empowers developers to programmatically monitor and manage UniFi deployments at scale. It provides comprehensive tools to access and control your UniFi devices’ data, enabling you to retrieve detailed information, monitor performance metrics, and efficiently manage your network infrastructure.  
 
The Site Manager API primarily focuses on extracting data from the UniFi Site Manager (unifi.ui.com). Subsequent versions will extend functionality to include more granular configurations, facilitating the management of individual sites and their associated devices.  
 
Your feedback is invaluable in helping us enhance and tailor the API to better address your specific requirements.

Authentication

An API Key serves as a unique identifier used to authenticate API requests. These keys are essential for securing access to your UniFi account and its associated devices. Each key is linked to the specific UI account that generated it, ensuring secure and personalized API interactions.

Obtaining an API Key

  1. Sign in to the UniFi Site Manager at unifi.ui.com/api.
  2. Select “Create API Key.”
  3. Copy the generated key and store it securely, as it will only be displayed once.
  4. Ensure the key is properly hashed and securely stored.

Use the API Key

Incorporate the API key into the X-API-Key header for all requests. Follow the example provided, replacing YOUR_API_KEY with your actual API key.

Example 
curl -X GET 'https://api.ui.com/v1/hosts' \
 -H 'X-API-KEY: YOUR_API_KEY' \
 -H 'Accept: application/json'

Rate Limiting

The API rate limits are enforced based on the API version:

  • Early Access (EA) version:

    • 100 requests per minute

  • v1 stable release:

    • 10,000 requests per minute

If you exceed these limits, the server will respond with a 429 Too Many Requests status code. The response will include a Retry-After header indicating the number of seconds to wait before making additional requests, following the RFC specification.

2 - Response Format

Explore the standardized JSON response format for UniFi Site Manager API, including success and error response structures, common error codes, and best practices for error handling

Response Format

All Site Manager API responses follow a consistent JSON structure to ensure predictable handling across different endpoints.

Success Response Structure

A successful API response will have the following format:

Example 

{
  // Response payload varies by endpoint. The data field can be either an array or an object.
  "data":  []/{},
  "httpStatusCode": 200,
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
  • The data object/array contains the actual response payload, which varies by endpoint.
  • The httpStatusCode field indicates the HTTP status of the response (usually 200 for success).
  • The traceId is a unique identifier for the request useful for troubleshooting.

Error Response Structure

All error responses follow this consistent format:

Example 

{
  "code": "NOT_FOUND",
  "httpStatusCode": 404,
  "message": "thing not found: 942A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
  • code: A machine-readable error code (uppercase string)
  • httpStatusCode: The HTTP status code (as a number)
  • message: A detailed description of the error
  • traceId: A unique identifier for the request (useful for troubleshooting)

Common Error Codes

HTTP Status Error Code Description Example Message
400 BAD_REQUEST The request was improperly formatted or contained invalid parameters “invalid request parameters”
401 UNAUTHORIZED Authentication failed or credentials are missing “unauthorized”
403 FORBIDDEN The authenticated user lacks permission to access the resource “insufficient permissions”
404 NOT_FOUND The requested resource does not exist “thing not found: {id}”
429 RATE_LIMIT The request exceeds the rate limit “rate limit exceeded, retry after 5.372786998s”
500 SERVER_ERROR An unexpected error occurred on the server “failed to get resource by ID”
502 BAD_GATEWAY The server received an invalid response from an upstream server “bad gateway”

Handling Errors

When handling errors from the API, we recommend:

  1. Check the HTTP status code first to determine the general category of error
  2. Parse the error code for programmatic handling of specific error conditions
  3. Log the traceId for all errors to assist with troubleshooting
  4. Implement retries with exponential backoff for 429 and 5xx errors
  5. Extract retry information from the header for rate limit errors
  6. Display user-friendly messages based on the error’s message

For rate limit errors, parse the retry time from the header and wait at least that long before retrying.

3 - Version Control

Learn about UniFi Site Manager API versioning policy, including version lifecycle, deprecation guidelines, and best practices for API version management

Available Endpoints

There are two versions of the Site Manager API:

  • Official (v1): Fully-stable and backward compatible APIs with long-term support.
    • Endpoint: https://api.ui.com/v1/...
  • Early Access (EA): APIs that have undergone extensive testing but are still in the evaluation and feedback phase. These may be enhanced based on user input.
    • Endpoint: https://api.ui.com/ea/...

Backward Compatibility

When an EA endpoint is promoted to Official (e.g., api.ui.com/ea/ → api.ui.com/v1/), your existing integration using the EA endpoint will continue to function as expected — no immediate changes required.

Optional fields during EA

In the Early Access version of our APIs, all fields within response.data are considered optional. This flexible design facilitates ongoing iteration and improvement of our API. We strongly recommend building your integrations with this optionality in mind to ensure compatibility with future updates.

Backward-Compatible Changes

The following modifications are considered backward-compatible and may be applied to the API without advance notice:

  • Adding new API resources or endpoints
  • Adding new optional request parameters to existing API methods
  • Adding new properties to existing API responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of opaque strings (such as object IDs, error messages, and other human-readable strings)

Best Practice: Design your integration to handle unexpected response structures gracefully, including unfamiliar properties, null values, and missing attributes. Please report any suspected breaking changes via our feedback form.

4 - List Hosts

Retrieves a list of all hosts associated with the UI account making the API call.

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.
List Hosts
GET
/v1/hosts

Description

Retrieves a list of all hosts associated with the UI account making the API call.

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.

Parameters

pageSize
string
Optional
query
Number of items to return per page
nextToken
string
Optional
query
Token for pagination to retrieve the next set of results
Example 
curl -X GET 'https://api.ui.com/v1/hosts?pageSize=10&nextToken=602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
code
Error code from upstream
data
array
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
nextToken
string
Pagination token for fetching the next set of results
Example Response 
{
  "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"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to list hosts
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to list hosts",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

5 - Get Host by ID

Retrieves detailed information about a specific host by ID.

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.
Get Host by ID
GET
/v1/hosts/{id}

Description

Retrieves detailed information about a specific host by ID.

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.

Parameters

id
string
Required
path
Unique identifier of the host
Example 
curl -X GET 'https://api.ui.com/v1/hosts/{id}' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
console
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

200
network-server
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

404
not found
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "NOT_FOUND",
  "httpStatusCode": 404,
  "message": "thing not found: 942A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to get host
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to get host",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

6 - List Sites

Retrieves a list of all sites (from hosts running the UniFi Network application) associated with the UI account making the API call.

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.
List Sites
GET
/v1/sites

Description

Retrieves a list of all sites (from hosts running the UniFi Network application) associated with the UI account making the API call.

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.

Parameters

pageSize
string
Optional
query
Number of items to return per page
nextToken
string
Optional
query
Token for pagination to retrieve the next set of results
Example 
curl -X GET 'https://api.ui.com/v1/sites?pageSize=10&nextToken=602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
code
Error code from upstream
data
array
Generic response data, specific schema depends on the endpoint
siteId
string
Unique identifier of the site
hostId
string
Unique identifier of the host device managing this site
meta
Site metadata including name, description, timezone, and gateway MAC address. Structure may vary depending on the UniFi Network version
statistics
Site statistics including device counts, client counts, and network performance metrics. Structure may vary depending on the UniFi Network version
permission
string
Permission level of the current user for this site (admin, readonly, etc.)
isOwner
boolean
Indicates if the current user is the owner of this site
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
nextToken
string
Pagination token for fetching the next set of results
Example Response 
{
  "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"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to list sites
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to list sites",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

7 - List Devices

Retrieves a list of UniFi devices managed by hosts where the UI account making the API call is the owner or a super admin.

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.
List Devices
GET
/v1/devices

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.

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.

Parameters

hostIds[]
array[string]
Optional
query
List of host IDs to filter the results
time
string
Optional
query
Last processed timestamp of devices in RFC3339 format
pageSize
string
Optional
query
Number of items to return per page
nextToken
string
Optional
query
Token for pagination to retrieve the next set of results
Example 
curl -X GET 'https://api.ui.com/v1/devices?hostIds[]=900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789&hostIds[]=900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321&time=2025-04-15T02:11:47Z&pageSize=10&nextToken=602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
code
Error code from upstream
data
array
Generic response data, specific schema depends on the endpoint
hostId
string
Unique identifier of the host device
hostName
string
Name of the host device
devices
array
Array of devices managed by this host
id
string
Unique identifier of the device
mac
string
MAC address of the device
name
string
User-defined name of the device
model
string
Model name of the device
shortname
string
Short identifier of the device model (e.g., UDMPROSE)
ip
string
IP address of the device
productLine
string
Product line of the device (network, protect, etc.)
status
string
Current connection status of the device (online, offline, etc.)
version
string
Current firmware version of the device
firmwareStatus
string
Status of device firmware (upToDate, updateAvailable, etc.)
updateAvailable
string
Version of firmware update available for the device, if any
isConsole
boolean
Indicates if the device is a console device
isManaged
boolean
Indicates if the device is managed by the controller
startupTime
string
date-time
Time when the device was last started in RFC3339 format
adoptionTime
string
Time when the device was adopted in RFC3339 format
note
string
User-defined notes for the device
uidb
UI-specific metadata including images and identifiers
updatedAt
string
date-time
Last update time in RFC3339 format
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
nextToken
string
Pagination token for fetching the next set of results
Example Response 
{
  "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": "2025-04-15T02:11:47Z"
    }
  ],
  "httpStatusCode": 200,
  "traceId": "a7dc15e0eb4527142d7823515b15f87d",
  "nextToken": "ba8e384e-3308-4236-b344-7357657351ca"
}

Responses

400
invalid parameter
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "parameter_invalid",
  "httpStatusCode": 400,
  "message": "invalid time format: 2024-04-24",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to list devices
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to list devices",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

8 - Get ISP Metrics

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.
Get ISP Metrics
GET
/ea/isp-metrics/{type}

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.

Parameters

type
string
Required
path
Specifies whether metrics are returned using 5m or 1h intervals
beginTimestamp
string
Optional
query
The earliest timestamp to retrieve data from (RFC3339 format)
endTimestamp
string
Optional
query
The latest timestamp to retrieve data up to (RFC3339 format)
duration
string
Optional
query
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.
Example 
curl -X GET 'https://api.ui.com/ea/isp-metrics/{type}?beginTimestamp=2024-06-30T13:35:00Z&endTimestamp=2024-06-30T15:35:00Z' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
data
array
Generic response data, specific schema depends on the endpoint
metricType
string
periods
array
data
object
wan
object
avgLatency
integer
download_kbps
integer
downtime
integer
ispAsn
string
ispName
string
maxLatency
integer
packetLoss
integer
upload_kbps
integer
uptime
integer
metricTime
string
date-time
version
string
hostId
string
siteId
string
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

400
invalid parameter
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "parameter_invalid",
  "httpStatusCode": 400,
  "message": "invalid beginTimestamp format: 2024-06-30",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to get ISP metrics
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to get ISP metrics",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

9 - Query ISP Metrics

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.

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.
Query ISP Metrics
POST
/ea/isp-metrics/{type}/query

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.

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.

Parameters

type
string
Required
path
Specifies whether metrics are returned using 5m or 1h intervals

Body Parameters

sites
array
beginTimestamp
string
date-time
hostId
string
endTimestamp
string
date-time
siteId
string
Example 
curl -X POST 'https://api.ui.com/ea/isp-metrics/{type}/query' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY' \
  -d '{
  "sites": [
    {
      "beginTimestamp": "2019-08-24T14:15:22Z",
      "hostId": "string",
      "endTimestamp": "2019-08-24T14:15:22Z",
      "siteId": "string"
    }
  ]
}'

Responses

200
ok
data
object
Generic response data, specific schema depends on the endpoint
metrics
array
metricType
string
periods
array
data
object
wan
object
avgLatency
integer
download_kbps
integer
downtime
integer
ispAsn
string
ispName
string
maxLatency
integer
packetLoss
integer
upload_kbps
integer
uptime
integer
metricTime
string
date-time
version
string
hostId
string
siteId
string
message
string
status
string
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

200
partial success
data
object
Generic response data, specific schema depends on the endpoint
metrics
array
metricType
string
periods
array
data
object
wan
object
avgLatency
integer
download_kbps
integer
downtime
integer
ispAsn
string
ispName
string
maxLatency
integer
packetLoss
integer
upload_kbps
integer
uptime
integer
metricTime
string
date-time
version
string
hostId
string
siteId
string
message
string
status
string
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

400
invalid parameter
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "parameter_invalid",
  "httpStatusCode": 400,
  "message": "invalid beginTimestamp format: 2024-06-30",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to query ISP metrics
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to query ISP metrics",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

10 - List SD-WAN Configs

Retrieves a list of all SD-WAN configurations associated with the UI account making the API call.
List SD-WAN Configs
GET
/ea/sd-wan-configs

Description

Retrieves a list of all SD-WAN configurations associated with the UI account making the API call.
Example 
curl -X GET 'https://api.ui.com/ea/sd-wan-configs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
data
array
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the SD-WAN config
name
string
Name of the SD-WAN config
type
string
Type of SD-WAN config - Currently only supports sdwan-hbsp
Values:
sdwan-hbsp
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "data": [
    {
      "id": "9304163b-680d-4de8-a7a0-7617e328911d",
      "name": "SD-WAN test",
      "type": "sdwan-hbsp"
    }
  ],
  "httpStatusCode": 200,
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to list network cloud SD-WAN configs
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to list network cloud SD-WAN configs",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

11 - Get SD-WAN Config by ID

Retrieves detailed information about a specific SD-WAN configuration by ID.
Get SD-WAN Config by ID
GET
/ea/sd-wan-configs/{id}

Description

Retrieves detailed information about a specific SD-WAN configuration by ID.

Parameters

id
string
Required
path
Unique identifier of the SD-WAN configuration
Example 
curl -X GET 'https://api.ui.com/ea/sd-wan-configs/{id}' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the SD-WAN config
name
string
Name of the SD-WAN config
type
string
Type of SD-WAN config - Currently only supports sdwan-hbsp
Values:
sdwan-hbsp
variant
string
Variant of SD-WAN configuration
Values:
distributed
failover
single
settings
object
Advanced settings
hubsInterconnect
boolean
spokeToHubTunnelsMode
string
Values:
maxResiliency
redundant
scalable
spokesAutoScaleAndNatEnabled
boolean
Auto-assigns subnet and routes; otherwise, users enter them manually.
spokesAutoScaleAndNatRange
string
Subnet in CIDR format, Example: 172.16.0.0/12
spokesIsolate
boolean
Setting for NET: Spokes can reach hubs but not other spokes.
spokeStandardSettingsEnabled
boolean
Enable spoke standard settings
spokeStandardSettingsValues
object
Spoke standard settings
primaryWan
string
Example: ‘WAN’
wanFailover
boolean
Use fail over WAN.
spokeToHubRouting
string
Values:
custom
geo
hubs
array
id
string
hostId
string
siteId
string
networkIds
array[string]
Ids of networks belonging to the hub
routes
array[string]
Subnets in CIDR format: 10.0.0.0/24
primaryWan
string
Example: ‘WAN’
wanFailover
boolean
Use fail over WAN.
spokes
array
id
string
hostId
string
siteId
string
networkIds
array[string]
Ids of networks belonging to the spoke
routes
array[string]
Subnets in CIDR format: 10.0.0.0/24
primaryWan
string
Example: ‘WAN’
wanFailover
boolean
Use fail over WAN.
hubsPriority
array[string]
Non-null for distributed topology and spokeToHubRouting=custom
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

404
config not found
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "not_found",
  "httpStatusCode": 404,
  "message": "config not found",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to get network cloud SD-WAN config by ID
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to get network cloud SD-WAN config by ID",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

12 - Get SD-WAN Config Status

Retrieves the status of a specific SD-WAN configuration, including deployment progress, errors, and associated hubs.
Get SD-WAN Config Status
GET
/ea/sd-wan-configs/{id}/status

Description

Retrieves the status of a specific SD-WAN configuration, including deployment progress, errors, and associated hubs.

Parameters

id
string
Required
path
Unique identifier of the SD-WAN configuration
Example 
curl -X GET 'https://api.ui.com/ea/sd-wan-configs/{id}/status' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the SD-WAN configuration
fingerprint
string
A unique identifier representing the current state of the configuration.
updatedAt
integer
int64
The timestamp of the last update to the SD-WAN configuration.
hubs
array
List of hubs in SD-WAN configuration
id
string
Unique identifier of the hub
hostId
string
siteId
string
name
string
primaryWanStatus
object
ip
string
IP format: 10.0.0.1
latency
number
double
internetIssues
array
If WAN experience issues
wanId
string
secondaryWanStatus
object
ip
string
IP format: 10.0.0.1
latency
number
double
internetIssues
array
If WAN experience issues
wanId
string
errors
array
warnings
array
numberOfTunnelsUsedByOtherFeatures
integer
networks
array
networkId
string
name
string
errors
array
warnings
array
routes
array
routeValue
string
subnet in CIDR format: 10.0.0.0/24
errors
array
warnings
array
applyStatus
string
The current status of the hub configuration application.
Values:
ok
creating
updating
removing
createFailed
updateFailed
removeFailed
spokes
array
A list of spokes associated with the SD-WAN config.
id
string
hostId
string
siteId
string
name
string
primaryWanStatus
object
ip
string
IP format: 10.0.0.1
latency
number
double
internetIssues
array
If WAN experience issues
wanId
string
secondaryWanStatus
object
ip
string
IP format: 10.0.0.1
latency
number
double
internetIssues
array
If WAN experience issues
wanId
string
errors
array
warnings
array
numberOfTunnelsUsedByOtherFeatures
integer
networks
array
networkId
string
name
string
errors
array
A list of error messages related to the network, if any.
warnings
array
A list of warning messages related to the network, if any.
routes
array
routeValue
string
subnet in CIDR format: 10.0.0.0/24
errors
array
warnings
array
connections
array
hubId
string
tunnels
array
spokeWanId
string
hubWanId
string
status
string
The current status of the tunnel connection.
Values:
connected
disconnected
pending
applyStatus
string
The current status of the hub configuration application.
Values:
ok
creating
updating
removing
createFailed
updateFailed
removeFailed
lastGeneratedAt
integer
int64
The timestamp of the last generation of the SD-WAN configuration.
generateStatus
string
The status of the configuration generation process.
Values:
OK
GENERATING
GENERATE_FAILED
errors
array
A list of error messages related to the configuration, if any.
warnings
array
A list of warning messages related to the configuration, if any.
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response 
{
  "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"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

404
config not found
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "not_found",
  "httpStatusCode": 404,
  "message": "config not found",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to get network cloud SD-WAN config status by ID
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to get network cloud SD-WAN config status by ID",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}