---
agentTools:
  projectIndex: https://meshblu-socketio.readme.io/llms.txt
---

# Device

Retrieve a single device from the Meshblu registry.

Retrieve a device from the Meshblu device registry by it's `uuid`. In order to retrieve a target device, your connection must be authenticated as a device that is in the target device's `discover.view` whitelist. See the [Meshblu whitelist documentation](https://meshblu.readme.io/docs/whitelists-2-0) for more information.

### Event: `"device"`, `query`, `callback`

* `query` Query object, must contain only the `uuid` property.
  * `uuid` UUID of the device to retrieve.
* `callback` Function that will be called with a `result`.
  * `result` Object passed to the callback. Contains either the `device` or `error` key, but never both.
    * `device` The full device record from the Meshblu registry.
    * `error` String explaining the what went wrong. Is only present if something went wrong

[block:callout]
{
  "type": "warning",
  "title": "Check the permissions",
  "body": "Your device must exist in the other device's `discover.view` whitelist or no device will be returned. See the [Meshblu whitelist documentation](https://meshblu.readme.io/docs/whitelists-2-0) for more information."
}
[/block]

[block:callout]
{
  "type": "info",
  "body": "In Meshblu, it is not possible to distinguish between a device not existing and not having permission to view a device. In most of the Meshblu API calls, the error in both cases yields the protocol-specific equivalent of an `HTTP 404: Not Found`. The Socket.IO API, however, returns the error `Forbidden`. This is for backwards compatibility and will likely change with the next major version release of the Socket.IO API.",
  "title": "No 404"
}
[/block]

[block:api-header]
{
  "type": "basic",
  "title": "Successful Response"
}
[/block]

When requesting a valid device that the authorized device may view:

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"device\": {\n    \"uuid\": \"26de691f-8068-4cdc-907a-4cb5961a1aba\",\n    \"online\": true,\n    \"color\": \"green\"\n  }\n}",
      "language": "json",
      "name": "response.json"
    }
  ]
}
[/block]

[block:api-header]
{
  "type": "basic",
  "title": "Error Response"
}
[/block]

When requesting a non-existing device, or a device the authenticated device may not view:

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"error\": \"Forbidden\"\n}\n",
      "language": "json",
      "name": "error-response.json"
    }
  ]
}
[/block]