Devices

Manage AsaHome OS devices in your account.

Endpoints Overview

Method	Endpoint	Description	Auth
POST	`/devices/register`	Register a new device	Yes
GET	`/devices`	List user's devices	Yes
GET	`/devices/:id`	Get device details	Yes
PUT	`/devices/:id`	Update device	Yes
POST	`/devices/:id/link`	Link device to user	Yes
POST	`/devices/auth/:uuid`	Get device auth token	Yes
POST	`/devices/heartbeat/:uuid`	Device heartbeat	Yes

Base URL: https://cloud.asahome.io/api/v1

POST Register Device

Request

POST /api/v1/devices/register

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Request Body

Field	Type	Required	Description
`uuid`	string	Yes	Device UUID (from AsaHome OS)
`deviceId`	string	Yes	Human-readable device ID
`name`	string	Yes	Display name for the device
`ipAddress`	string	No	Local IP address
`port`	string	No	Device API port (default: 8123)
`metadata`	object	No	Additional device information

Example

curl -X POST "https://cloud.asahome.io/api/v1/devices/register" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "deviceId": "asahome-home-001",
    "name": "Home Hub",
    "ipAddress": "192.168.1.100",
    "port": "8123",
    "metadata": {
      "version": "2024.1.0",
      "location": "Living Room"
    }
  }'

Response

{
  "id": "device-internal-uuid",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "deviceId": "asahome-home-001",
  "name": "Home Hub",
  "ipAddress": "192.168.1.100",
  "port": "8123",
  "isOnline": false,
  "metadata": {
    "version": "2024.1.0",
    "location": "Living Room"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

The registering user automatically becomes the device owner.

GET List Devices

Retrieve all devices the authenticated user has access to.

Request

GET /api/v1/devices

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page
`online`	boolean	-	Filter by online status

Example

curl -X GET "https://cloud.asahome.io/api/v1/devices?online=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "data": [
    {
      "id": "device-uuid-1",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "deviceId": "asahome-home-001",
      "name": "Home Hub",
      "isOnline": true,
      "lastSeenAt": "2024-01-15T10:30:00.000Z",
      "role": "owner"
    },
    {
      "id": "device-uuid-2",
      "uuid": "550e8400-e29b-41d4-a716-446655440001",
      "deviceId": "asahome-office-001",
      "name": "Office Hub",
      "isOnline": false,
      "lastSeenAt": "2024-01-14T15:00:00.000Z",
      "role": "editor"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

GET Get Device

Retrieve details of a specific device.

Request

GET /api/v1/devices/:id

Path Parameters

Parameter	Type	Description
`id`	string	Device ID (UUID)

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Example

curl -X GET "https://cloud.asahome.io/api/v1/devices/device-uuid-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "id": "device-uuid-1",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "deviceId": "asahome-home-001",
  "name": "Home Hub",
  "ipAddress": "192.168.1.100",
  "port": "8123",
  "isOnline": true,
  "lastSeenAt": "2024-01-15T10:30:00.000Z",
  "metadata": {
    "version": "2024.1.0",
    "location": "Living Room"
  },
  "role": "owner",
  "users": [
    {
      "id": "user-uuid-1",
      "email": "owner@example.com",
      "role": "owner"
    },
    {
      "id": "user-uuid-2",
      "email": "family@example.com",
      "role": "editor"
    }
  ],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

PUT Update Device

Update device details. Only the device owner can update.

Request

PUT /api/v1/devices/:id

Path Parameters

Parameter	Type	Description
`id`	string	Device ID (UUID)

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Request Body

Field	Type	Required	Description
`name`	string	No	Display name
`ipAddress`	string	No	Local IP address
`port`	string	No	Device API port
`metadata`	object	No	Additional info

Example

curl -X PUT "https://cloud.asahome.io/api/v1/devices/device-uuid-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Home Hub",
    "metadata": {
      "version": "2024.2.0",
      "location": "Living Room"
    }
  }'

Response

{
  "id": "device-uuid-1",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "deviceId": "asahome-home-001",
  "name": "Main Home Hub",
  "ipAddress": "192.168.1.100",
  "port": "8123",
  "isOnline": true,
  "metadata": {
    "version": "2024.2.0",
    "location": "Living Room"
  },
  "updatedAt": "2024-01-15T11:00:00.000Z"
}

Error Responses

Forbidden (403)

{
  "statusCode": 403,
  "message": "Only the device owner can update device settings",
  "error": "Forbidden"
}

POST Link Device

Link an existing device to a user with a specific role.

Request

POST /api/v1/devices/:id/link

Path Parameters

Parameter	Type	Description
`id`	string	Device ID (UUID)

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Request Body

Field	Type	Required	Description
`email`	string	Yes	User email to link
`role`	string	Yes	Role: `owner`, `editor`, or `viewer`

Example

curl -X POST "https://cloud.asahome.io/api/v1/devices/device-uuid-1/link" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "family@example.com",
    "role": "editor"
  }'

Response

{
  "success": true,
  "deviceUser": {
    "id": "device-user-uuid",
    "userId": "user-uuid-2",
    "deviceId": "device-uuid-1",
    "role": "editor",
    "isActive": true,
    "createdAt": "2024-01-15T11:00:00.000Z"
  }
}

Role Permissions

Role	View	Control	Settings	Delete	Share
`owner`	Yes	Yes	Yes	Yes	Yes
`editor`	Yes	Yes	No	No	No
`viewer`	Yes	No	No	No	No

POST Get Device Auth Token

Generate an authentication token for the device to connect to the WebSocket tunnel.

Request

POST /api/v1/devices/auth/:uuid

Path Parameters

Parameter	Type	Description
`uuid`	string	Device UUID

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <accessToken>`

Example

curl -X POST "https://cloud.asahome.io/api/v1/devices/auth/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

The device uses this token to authenticate with the WebSocket tunnel.

POST Device Heartbeat

Update device online status and metadata. Called periodically by the AsaHome OS device.

Request

POST /api/v1/devices/heartbeat/:uuid

Path Parameters

Parameter	Type	Description
`uuid`	string	Device UUID

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <deviceToken>`

Request Body

Field	Type	Required	Description
`ipAddress`	string	No	Current local IP
`metadata`	object	No	Updated metadata

Example

curl -X POST "https://cloud.asahome.io/api/v1/devices/heartbeat/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAddress": "192.168.1.100",
    "metadata": {
      "uptime": 86400,
      "entities": 150
    }
  }'

Response

{
  "success": true,
  "device": {
    "id": "device-uuid-1",
    "isOnline": true,
    "lastSeenAt": "2024-01-15T11:00:00.000Z"
  }
}

Heartbeat Interval

Devices should send a heartbeat every 30-60 seconds. If no heartbeat is received for 5 minutes, the device is marked offline.

Device Object

Full Device Object

Field	Type	Description
`id`	string	Internal device ID
`uuid`	string	Device UUID (from AsaHome OS)
`deviceId`	string	Human-readable device ID
`name`	string	Display name
`ipAddress`	string	Last known local IP
`port`	string	Device API port
`isOnline`	boolean	Current online status
`lastSeenAt`	string	Last heartbeat timestamp
`metadata`	object	Additional device info
`createdAt`	string	Registration timestamp
`updatedAt`	string	Last update timestamp

Device User Relationship

Field	Type	Description
`id`	string	Relationship ID
`userId`	string	User ID
`deviceId`	string	Device ID
`role`	string	`owner`, `editor`, or `viewer`
`isActive`	boolean	Link active status

Endpoints Overview​

POST Register Device​

Request​

Headers​

Request Body​

Example​

Response​

GET List Devices​

Request​

Headers​

Query Parameters​

Example​

Response​

GET Get Device​

Request​

Path Parameters​

Headers​

Example​

Response​

PUT Update Device​

Request​

Path Parameters​

Headers​

Request Body​

Example​

Response​

Error Responses​

Forbidden (403)​

POST Link Device​

Request​

Path Parameters​

Headers​

Request Body​

Example​

Response​

Role Permissions​

POST Get Device Auth Token​

Request​

Path Parameters​

Headers​

Example​

Response​

POST Device Heartbeat​

Request​

Path Parameters​

Headers​

Request Body​

Example​

Response​

Device Object​

Full Device Object​

Device User Relationship​

Endpoints Overview

POST Register Device

Request

Headers

Request Body

Example

Response

GET List Devices

Request

Headers

Query Parameters

Example

Response

GET Get Device

Request

Path Parameters

Headers

Example

Response

PUT Update Device

Request

Path Parameters

Headers

Request Body

Example

Response

Error Responses

Forbidden (403)

POST Link Device

Request

Path Parameters

Headers

Request Body

Example

Response

Role Permissions

POST Get Device Auth Token

Request

Path Parameters

Headers

Example

Response

POST Device Heartbeat

Request

Path Parameters

Headers

Request Body

Example

Response

Device Object

Full Device Object

Device User Relationship