{
"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/connector/consoles/{id}/*path": {
"delete": {
"description": "Forward DELETE requests to UniFi applications using RESTful HTTP methods.
**Request Flow**: The request is proxied through `api.ui.com` cloud endpoint to the remote console at `http://127.0.0.1/proxy/[path]` with DELETE method.
**Requirements**:
- Console firmware version must >= 5.0.3
- For non-organization API keys: Limited to API key owner's consoles only (cannot access other admins' consoles)
- For organization API keys: Can access any console within the organization
**Rate Limit**:
- Each console is limited to 100 requests per minute
**Limits**:
- Request timeout: each proxied request must complete within 25 seconds; otherwise it is terminated and a timeout error is returned
- Response body size: the upstream response body is limited to 10 MB; larger responses are not supported
**API Documentation**:
- Network API: [https://developer.ui.com/network](https://developer.ui.com/network)
- Protect API: [https://developer.ui.com/protect](https://developer.ui.com/protect)
- InnerSpace API: [https://developer.ui.com/innerspace](https://developer.ui.com/innerspace)
**Response**: On success, the upstream API response is passed through directly. On error, a standardized error schema is returned.",
"operationId": "ConnectorDelete",
"parameters": [
{
"description": "Host ID to proxy the request to",
"example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "API path to proxy",
"example": "/proxy/network/integration/v1/sites/{siteId}/hotspot/vouchers",
"in": "path",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"delete vouchers response": {
"value": {
"vouchersDeleted": 0
}
}
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
},
"description": "200"
},
"400": {
"content": {
"application/json": {
"examples": {
"invalid parameter": {
"value": {
"code": "parameter_invalid",
"httpStatusCode": 400,
"message": "path is invalid",
"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"
},
"403": {
"content": {
"application/json": {
"examples": {
"forbidden": {
"value": {
"code": "forbidden",
"httpStatusCode": 403,
"message": "insufficient permissions or not the owner of the 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": "403"
},
"408": {
"content": {
"application/json": {
"examples": {
"device timeout": {
"value": {
"code": "DeviceTimeout",
"httpStatusCode": 408,
"message": "Device connection timeout",
"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": "408"
},
"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 proxy request": {
"value": {
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to proxy request",
"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": "Connector - DELETE",
"tags": [
"cloud-connector"
],
"x-position": 13
},
"get": {
"description": "Forward GET requests to UniFi applications using RESTful HTTP methods.
**Request Flow**: The request is proxied through `api.ui.com` cloud endpoint to the remote console at `http://127.0.0.1/proxy/[path]` with GET method.
**Requirements**:
- Console firmware version must >= 5.0.3
- For non-organization API keys: Limited to API key owner's consoles only (cannot access other admins' consoles)
- For organization API keys: Can access any console within the organization
**Rate Limit**:
- Each console is limited to 100 requests per minute
**Limits**:
- Request timeout: each proxied request must complete within 25 seconds; otherwise it is terminated and a timeout error is returned
- Response body size: the upstream response body is limited to 10 MB; larger responses are not supported
**API Documentation**:
- Network API: [https://developer.ui.com/network](https://developer.ui.com/network)
- Protect API: [https://developer.ui.com/protect](https://developer.ui.com/protect)
- InnerSpace API: [https://developer.ui.com/innerspace](https://developer.ui.com/innerspace)
**Examples**:
- Network: `GET /v1/connector/consoles/{id}/network/integration/v1/sites` retrieves network sites
- Protect: `GET /v1/connector/consoles/{id}/protect/integration/v1/meta/info` retrieves protect application info
**Response**: On success, the upstream API response is passed through directly. On error, a standardized error schema is returned.",
"operationId": "ConnectorGet",
"parameters": [
{
"description": "Host ID to proxy the request to",
"example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "API path to proxy",
"example": "/proxy/network/integration/v1/sites",
"in": "path",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"network sites response": {
"value": {
"count": 1,
"data": [
{
"id": "88f7af54-98f8-306a-a1c7-c9349722b1f6",
"internalReference": "default",
"name": "Default"
}
],
"limit": 25,
"offset": 0,
"totalCount": 1
}
},
"protect info response": {
"value": {
"applicationVersion": "6.1.79"
}
}
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
},
"description": "200"
},
"400": {
"content": {
"application/json": {
"examples": {
"invalid parameter": {
"value": {
"code": "parameter_invalid",
"httpStatusCode": 400,
"message": "path is invalid",
"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"
},
"403": {
"content": {
"application/json": {
"examples": {
"forbidden": {
"value": {
"code": "forbidden",
"httpStatusCode": 403,
"message": "insufficient permissions or not the owner of the 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": "403"
},
"408": {
"content": {
"application/json": {
"examples": {
"device timeout": {
"value": {
"code": "DeviceTimeout",
"httpStatusCode": 408,
"message": "Device connection timeout",
"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": "408"
},
"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 proxy request": {
"value": {
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to proxy request",
"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": "Connector - GET",
"tags": [
"cloud-connector"
],
"x-position": 11
},
"patch": {
"description": "Forward PATCH requests to UniFi applications using RESTful HTTP methods.
**Request Flow**: The request is proxied through `api.ui.com` cloud endpoint to the remote console at `http://127.0.0.1/proxy/[path]` with PATCH method.
**Requirements**:
- Console firmware version must >= 5.0.3
- For non-organization API keys: Limited to API key owner's consoles only (cannot access other admins' consoles)
- For organization API keys: Can access any console within the organization
**Rate Limit**:
- Each console is limited to 100 requests per minute
**Limits**:
- Request timeout: each proxied request must complete within 25 seconds; otherwise it is terminated and a timeout error is returned
- Response body size: the upstream response body is limited to 10 MB; larger responses are not supported
**API Documentation**:
- Network API: [https://developer.ui.com/network](https://developer.ui.com/network)
- Protect API: [https://developer.ui.com/protect](https://developer.ui.com/protect)
- InnerSpace API: [https://developer.ui.com/innerspace](https://developer.ui.com/innerspace)
**Response**: On success, the upstream API response is passed through directly. On error, a standardized error schema is returned.",
"operationId": "ConnectorPatch",
"parameters": [
{
"description": "Host ID to proxy the request to",
"example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "API path to proxy",
"example": "/proxy/protect/integration/v1/viewers/{id}",
"in": "path",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"name": "Updated Viewer Name"
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"protect viewer response": {
"value": {
"id": "507f1f77bcf86cd799439011",
"liveview": "507f1f77bcf86cd799439012",
"modelKey": "viewer",
"name": "Living Room Viewer",
"state": "CONNECTED",
"streamLimit": 4
}
}
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
},
"description": "200"
},
"400": {
"content": {
"application/json": {
"examples": {
"invalid parameter": {
"value": {
"code": "parameter_invalid",
"httpStatusCode": 400,
"message": "path is invalid",
"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"
},
"403": {
"content": {
"application/json": {
"examples": {
"forbidden": {
"value": {
"code": "forbidden",
"httpStatusCode": 403,
"message": "insufficient permissions or not the owner of the 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": "403"
},
"408": {
"content": {
"application/json": {
"examples": {
"device timeout": {
"value": {
"code": "DeviceTimeout",
"httpStatusCode": 408,
"message": "Device connection timeout",
"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": "408"
},
"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 proxy request": {
"value": {
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to proxy request",
"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": "Connector - PATCH",
"tags": [
"cloud-connector"
],
"x-position": 14
},
"post": {
"description": "Forward POST requests to UniFi applications using RESTful HTTP methods.
**Request Flow**: The request is proxied through `api.ui.com` cloud endpoint to the remote console at `http://127.0.0.1/proxy/[path]` with POST method.
**Requirements**:
- Console firmware version must >= 5.0.3
- For non-organization API keys: Limited to API key owner's consoles only (cannot access other admins' consoles)
- For organization API keys: Can access any console within the organization
**Rate Limit**:
- Each console is limited to 100 requests per minute
**Limits**:
- Request timeout: each proxied request must complete within 25 seconds; otherwise it is terminated and a timeout error is returned
- Response body size: the upstream response body is limited to 10 MB; larger responses are not supported
**API Documentation**:
- Network API: [https://developer.ui.com/network](https://developer.ui.com/network)
- Protect API: [https://developer.ui.com/protect](https://developer.ui.com/protect)
- InnerSpace API: [https://developer.ui.com/innerspace](https://developer.ui.com/innerspace)
**Response**: On success, the upstream API response is passed through directly. On error, a standardized error schema is returned.",
"operationId": "ConnectorPost",
"parameters": [
{
"description": "Host ID to proxy the request to",
"example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "API path to proxy",
"example": "/proxy/network/integration/v1/sites/{siteId}/clients/{clientId}/actions",
"in": "path",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"action": "AUTHORIZE_GUEST_ACCESS"
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"success": {
"value": {
"success": true
}
}
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
},
"description": "200"
},
"400": {
"content": {
"application/json": {
"examples": {
"invalid parameter": {
"value": {
"code": "parameter_invalid",
"httpStatusCode": 400,
"message": "path is invalid",
"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"
},
"403": {
"content": {
"application/json": {
"examples": {
"forbidden": {
"value": {
"code": "forbidden",
"httpStatusCode": 403,
"message": "insufficient permissions or not the owner of the 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": "403"
},
"408": {
"content": {
"application/json": {
"examples": {
"device timeout": {
"value": {
"code": "DeviceTimeout",
"httpStatusCode": 408,
"message": "Device connection timeout",
"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": "408"
},
"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 proxy request": {
"value": {
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to proxy request",
"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": "Connector - POST",
"tags": [
"cloud-connector"
],
"x-position": 10
},
"put": {
"description": "Forward PUT requests to UniFi applications using RESTful HTTP methods.
**Request Flow**: The request is proxied through `api.ui.com` cloud endpoint to the remote console at `http://127.0.0.1/proxy/[path]` with PUT method.
**Requirements**:
- Console firmware version must >= 5.0.3
- For non-organization API keys: Limited to API key owner's consoles only (cannot access other admins' consoles)
- For organization API keys: Can access any console within the organization
**Rate Limit**:
- Each console is limited to 100 requests per minute
**Limits**:
- Request timeout: each proxied request must complete within 25 seconds; otherwise it is terminated and a timeout error is returned
- Response body size: the upstream response body is limited to 10 MB; larger responses are not supported
**API Documentation**:
- Network API: [https://developer.ui.com/network](https://developer.ui.com/network)
- Protect API: [https://developer.ui.com/protect](https://developer.ui.com/protect)
- InnerSpace API: [https://developer.ui.com/innerspace](https://developer.ui.com/innerspace)
**Response**: On success, the upstream API response is passed through directly. On error, a standardized error schema is returned.",
"operationId": "ConnectorPut",
"parameters": [
{
"description": "Host ID to proxy the request to",
"example": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "API path to proxy",
"example": "/proxy/network/integration/v1/sites/{siteId}/firewall/zones/{firewallZoneId}",
"in": "path",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"name": "Updated Firewall Zone"
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"firewall zone response": {
"value": {
"id": "ffcdb32c-6278-4364-8947-df4f77118df8",
"metadata": {
"isConfigurable": true,
"type": "system"
},
"name": "External"
}
}
},
"schema": {
"additionalProperties": {},
"type": "object"
}
}
},
"description": "200"
},
"400": {
"content": {
"application/json": {
"examples": {
"invalid parameter": {
"value": {
"code": "parameter_invalid",
"httpStatusCode": 400,
"message": "path is invalid",
"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"
},
"403": {
"content": {
"application/json": {
"examples": {
"forbidden": {
"value": {
"code": "forbidden",
"httpStatusCode": 403,
"message": "insufficient permissions or not the owner of the 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": "403"
},
"408": {
"content": {
"application/json": {
"examples": {
"device timeout": {
"value": {
"code": "DeviceTimeout",
"httpStatusCode": 408,
"message": "Device connection timeout",
"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": "408"
},
"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 proxy request": {
"value": {
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to proxy request",
"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": "Connector - PUT",
"tags": [
"cloud-connector"
],
"x-position": 12
}
},
"/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.
**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-06-15T07:21:27Z",
"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-06-15T07:21:27Z"
}
],
"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.
**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.
**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.
**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.
**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",
"description": "UniFi API"
}
],
"tags": [
{
"name": "cloud-connector",
"x-displayName": "Connector"
}
]
}