Devices

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 (available in https://app.xyte.io/settings/api_keys)

Value	Key
Organization Key	Authorization

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

This endpoint returns a paginated list of devices within the organization

Headers

Name	Type	Description
Authorization	String	API_KEY

Request Body

Name	Type	Description
page	String	Page number (default 1)
per_page	String	Number of devices per page (default 100)
space_id	String	Filter devices by space id

200: OK

{
    "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
}

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

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

The mac & sn / cloud_id parameters are required based on the method of authentication the device manufacturer defined. Consult the manufacturers data sheet to determine if sending of cloud_id or a combination of mac and sn is required.

Headers

Name	Type	Description
Authorization*	String	API_KEY

Request Body

Name	Type	Description
name	String	User friendly name
space_id	String	ID of target space. If not provided, the device will not be associated with the "unsorted space".
mac	String	MAC Address
sn	String	Serial Number
cloud_id	String	Cloud ID

200: OK

{
    "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"
    }
}

PATCH https://hub.xyte.io/core/v1/organization/devices/:id

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

Path Parameters

Name	Type	Description
id*	String	Device ID

Headers

Name	Type	Description
Authorization*	String	API_KEY

Request Body

Name	Type	Description
configuration	String	Configuration object (must abide by the schema defined by the manufacturer)

200: OK

{
    "success": true
}

DELETE https://hub.xyte.io/core/v1/organization/devices/:id

This endpoint deletes an existing device within the organization.

Path Parameters

Name	Type	Description
id*	String	Device ID

Headers

Name	Type	Description
Authorization*	String	API_KEY

200: OK

{
    "success": true
}

Error Handling

• 401 Unauthorized: If the api_key is not provided or is invalid.

• 403 Forbidden: If the user does not have permission to perform the requested action.

• 404 Not Found: If a device with the specified ID is not found.

• 422 Unprocessable Entity: If a required parameter is missing or invalid.