Get Host by ID
GET
/v1/hosts/{id}
Description
Retrieves detailed information about a specific host by ID.Note: The structure of the
userData and reportedState fields may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.Parameters
id
string
Required
path
Unique identifier of the host
Example
curl -X GET 'https://api.ui.com/v1/hosts/{id}' \
-H 'Accept: application/json' \
-H 'X-API-Key: API_KEY'Responses
200
console
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response
{
"data": {
"id": "70A7419783ED0000000006797F060000000006C719490000000062ABD4EA:1261206302",
"hardwareId": "e5bf13cd-98a7-5a96-9463-0d65d78cd3a4",
"type": "ucore",
"ipAddress": "220.130.137.169",
"owner": true,
"isBlocked": false,
"registrationTime": "",
"lastConnectionStateChange": "2024-04-16T02:52:54.193Z",
"latestBackupTime": "",
"userData": {
"apps": [
"users"
],
"consoleGroupMembers": [
{
"mac": "70A7419783ED",
"role": "UNADOPTED",
"roleAttributes": {
"applications": {
"access": {
"owned": false,
"required": false,
"supported": true
},
"connect": {
"owned": false,
"required": false,
"supported": true
},
"innerspace": {
"owned": false,
"required": false,
"supported": true
},
"network": {
"owned": false,
"required": true,
"supported": true
},
"protect": {
"owned": false,
"required": false,
"supported": true
},
"talk": {
"owned": false,
"required": false,
"supported": true
}
},
"candidateRoles": [
"PRIMARY"
],
"connectedState": "CONNECTED",
"connectedStateLastChanged": "2024-04-16T02:52:54.193Z"
},
"sysId": 59925
}
],
"controllers": [
"network",
"protect",
"access",
"talk",
"connect",
"innerspace"
],
"email": "example@ui.com",
"features": {
"deviceGroups": true,
"floorplan": {
"canEdit": true,
"canView": true
},
"manageApplications": true,
"notifications": true,
"pion": true,
"webrtc": {
"iceRestart": true,
"mediaStreams": true,
"twoWayAudio": true
}
},
"fullName": "UniFi User",
"localId": "d4eb483d-98a7-438b-abe1-f46628dff73f",
"permissions": {
"access.management": [
"admin"
],
"connect.management": [
"admin"
],
"innerspace.management": [
"admin"
],
"network.management": [
"admin"
],
"protect.management": [
"admin"
],
"system.management.location": [
"admin"
],
"system.management.user": [
"admin"
],
"talk.management": [
"admin"
]
},
"role": "owner",
"roleId": "c349b256-98a7-44ab-b8a1-13c437ea7742",
"status": "ACTIVE"
},
"reportedState": null
},
"httpStatusCode": 200,
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
200
network-server
data
object
Generic response data, specific schema depends on the endpoint
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
Example Response
{
"data": {
"id": "1d9cf3ee-0c0f-466e-933c-9af829f09b50",
"hardwareId": "b000b21e-0000-1111-add9-c1eed3897602",
"type": "network-server",
"ipAddress": "192.168.1.124",
"owner": true,
"isBlocked": false,
"registrationTime": "2024-02-07T10:25:21.981Z",
"lastConnectionStateChange": "2024-06-10T07:52:23.382Z",
"latestBackupTime": "",
"userData": null,
"reportedState": {
"controller_uuid": "b000b21e-0000-1111-add9-c1eed3897602",
"deviceId": "1d9cf3ee-0c0f-466e-933c-9af829f09b50",
"firmware_version": null,
"hardware_id": "b000b21e-0000-1111-add9-c1eed3897602",
"host_type": 0,
"hostname": "example-domain.ui.com",
"inform_port": 8080,
"ipAddrs": [
"192.168.1.124"
],
"mgmt_port": 8443,
"name": "Self-Hosted Site",
"override_inform_host": false,
"release_channel": "release",
"state": "connected",
"version": "8.3.11"
}
},
"httpStatusCode": 200,
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response
{
"code": "unauthorized",
"httpStatusCode": 401,
"message": "unauthorized",
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
404
not found
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response
{
"code": "NOT_FOUND",
"httpStatusCode": 404,
"message": "thing not found: 942A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694",
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Headers
Retry-After
string
example: 5
Example Response
{
"code": "rate_limit",
"httpStatusCode": 429,
"message": "rate limit exceeded, retry after 5.372786998s",
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
500
failed to get host
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response
{
"code": "server_error",
"httpStatusCode": 500,
"message": "failed to get host",
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
Responses
502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response
{
"code": "bad_gateway",
"httpStatusCode": 502,
"message": "bad gateway",
"traceId": "a7dc15e0eb4527142d7823515b15f87d"
}