Devices

Manage your devices through our API.

This API handles the Create, Read, Update, and Delete operations for devices within an organization.

Authorization

All requests must be authenticated and authorized by adding a special Header to each request containing the Organization Key. See how to get your API Keys which must be entered in the Authorization field.

ValueKey
Organization KeyAuthorization

List devices

This endpoint returns a paginated list of devices within the organization.

GET https://hub.xyte.io/core/v1/organization/devices

Headers

NameTypeDescription
Authorization*StringAPI_KEY

Request Body

pagestringPage number (default 1)
per_pagestringNumber of devices per page (default 100)
space_idstringFilter devices by space id

Response

{
    "items": [
        {
            "id": "xxxxxxxx",
            "name": "Demo",
            "sn": "445454",
            "mac": "43:x9:xx:56:xx:xx",
            "cloud_id": null,
            "status": "offline",
            "last_seen_at": "2023-03-12T10:19:56.274Z",
            "details": {
                "custom": "value"
            },
            "model": {
                "id": "xxxxx",
                "name": "Display - Test Device",
                "sub_model": null
            },
            "firmware": {
                "version": "1.0.0"
            },
            "space": {
                "id": xxx,
                "full_path": "Wiz/Berlin/Room #1"
            }
        },
        // More devices..
    ],
    "next_page": null
}

Claim a device

This endpoint creates a new device within the organization and associates it with the specified space.

Either the cloud_id or the mac and sn parameters are required, depending on the method of authentication the device manufacturer defined. Consult the manufacturers data sheet to determine which you need to send.

POST <https://hub.xyte.io/core/v1/organization/devices/claim>

Headers

NameTypeDescription
Authorization*StringAPI_KEY

Request Body

NameTypeDescription
namestringUser friendly name
space_idstringID of target space.

If not provided, the device will not be associated with the "unsorted space".
macstringMAC Address
snstringSerial Number
cloud_idstringCloud ID

Response

{
    "id": "xxxxx",
    "name": "xxxn Test",
    "sn": "XAt-xxxxxx",
    "mac": null,
    "cloud_id": "xxxxxxxxxx",
    "status": null,
    "last_seen_at": "2023-02-08T19:52:28.344Z",
    "details": {
        "custom": "data"
    },
    "model": {
        "id": "xxxxxxx-xxxxxxx",
        "name": "Trackpad",
        "sub_model": null
    },
    "firmware": {
        "version": "1.0.0"
    },
    "space": {
        "id": 11531,
        "full_path": "Wiz/Unsorted"
    }
}

Update a device

This endpoint updates the configuration of an existing device within the organization.

PATCH https://hub.xyte.io/core/v1/organization/devices/{{device_id}}

Path Parameters

NameTypeDescription
id*stringDeviceID

Headers

NameTypeDescription
Authorization*stringAPI_KEY

Request Body

NameTypeDescription
configurationstringConfiguration object (must abide by the schema defined by the manufacturer)

Response

{
    "success": true
}

Delete a device

This endpoint deletes an existing device within the organization.

DELETE https://hub.xyte.io/core/v1/organization/devices/{device_id}

Path Parameters

NameTypeDescription
id*stringDevice ID

Headers

NameTypeDescription
Authorization*stringAPI_KEY

Response

{
    "success": true
}

Error Handling

  • 401 Unauthorized: the api_key is not provided or is invalid.
  • 403 Forbidden: the user does not have permission to perform the requested action.
  • 404 Not Found: a device with the specified ID is not found.
  • 422 Unprocessable Entity: a required parameter is missing or invalid.