Device Base Module

Project: Pet Feeder | page_id: 1726

Device Module Authentication Interface Documentation

Overview

• Base path: /api
• Documentation scope: only includes device basic authentication interfaces
• Authentication method: request header X-Token
• Content-Type: application/json

Document Split

• This document: device basic interfaces, including list, detail, bind, unbind and update
• P2P proxy interfaces: see device-auth-p2p.md
• Live address and recording address interfaces: see device-auth-address.md

Authentication Header

Unified Response Format

{
  "code": 200,
  "msg": "Operation successful",
  "data": {}
}

Response Field Description

Common Authentication Failure Response

{
  "code": 401,
  "msg": "Not logged in or login expired",
  "data": null
}

{
  "code": 401,
  "msg": "Login has expired, please log in again",
  "data": null
}

Device Object Field Description

The data returned when getting the device list, device details or binding a device successfully may contain the following fields:

1. Get the Device List

• Path: /api/device/list
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "familyId": "family_001"
}

An empty object can also be passed:

{}

Success Response Example

{
  "code": 200,
  "msg": "Operation successful",
  "data": [
    {
      "id": "dev_001",
      "userId": 1,
      "familyId": "family_001",
      "name": "Living room feeder",
      "batteryLevel": 86,
      "isCharging": false,
      "foodLevel": 70,
      "firmwareVersion": "1.0.2",
      "totalFeedCount": 12,
      "todayFeedCount": 3,
      "lastStartTime": 1752297600,
      "lastCloseTime": 1752280000,
      "online": true,
      "isDisabled": false,
      "isNew": 0,
      "eip": "1.2.3.4",
      "cloudVer": "cloud-2026.05",
      "addr": "192.168.1.10",
      "createdAt": "2026-05-01T10:00:00Z",
      "updatedAt": "2026-05-09T10:00:00Z"
    }
  ]
}

Response Parameter Description

Failure Response Example

{
  "code": 500,
  "msg": "Failed to get the device list",
  "data": null
}

2. Get Device Details

• Path: /api/device/detail
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "deviceId": "dev_001"
}

Success Response Example

{
  "code": 200,
  "msg": "Operation successful",
  "data": {
    "id": "dev_001",
    "userId": 1,
    "familyId": "family_001",
    "name": "Living room feeder",
    "batteryLevel": 86,
    "isCharging": false,
    "foodLevel": 70,
    "firmwareVersion": "1.0.2",
    "totalFeedCount": 12,
    "todayFeedCount": 3,
    "lastStartTime": 1752297600,
    "lastCloseTime": 1752280000,
    "online": true,
    "isDisabled": false,
    "isNew": 0,
    "eip": "1.2.3.4",
    "cloudVer": "cloud-2026.05",
    "addr": "192.168.1.10",
    "createdAt": "2026-05-01T10:00:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Parameter error",
  "data": null
}

{
  "code": 404,
  "msg": "Device does not exist",
  "data": null
}

3. Bind a Device

• Path: /api/device/bind
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "deviceId": "dev_001",
  "familyId": "family_001",
  "name": "Living room feeder"
}

Success Response Example

{
  "code": 200,
  "msg": "Device bound successfully",
  "data": {
    "id": "dev_001",
    "userId": 1,
    "familyId": "family_001",
    "name": "Living room feeder"
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "familyId cannot be empty",
  "data": null
}

{
  "code": 400,
  "msg": "Device does not exist and cannot be bound",
  "data": null
}

{
  "code": 400,
  "msg": "This device is already bound by someone else",
  "data": null
}

{
  "code": 400,
  "msg": "The device name cannot exceed 30 characters",
  "data": null
}

{
  "code": 400,
  "msg": "The device name can only contain Chinese characters, letters, digits, underscores and hyphens",
  "data": null
}

4. Unbind a Device

• Path: /api/device/unbind
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "deviceId": "dev_001"
}

Success Response Example

{
  "code": 200,
  "msg": "Device unbound",
  "data": null
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Device does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "No permission to operate this device",
  "data": null
}

5. Update the Device Name

• Path: /api/device/update
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "deviceId": "dev_001",
  "name": "Dining room feeder"
}

Success Response Example

{
  "code": 200,
  "msg": "Update successful",
  "data": null
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Device does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "No permission to operate this device",
  "data": null
}

{
  "code": 400,
  "msg": "The device name cannot exceed 30 characters",
  "data": null
}

{
  "code": 400,
  "msg": "The device name can only contain Chinese characters, letters, digits, underscores and hyphens",
  "data": null
}

Appendix

Description

• This document only retains the device basic interfaces.
• The P2P proxy interfaces still pass parameters such as deviceId and sessionId through query; see device-auth-p2p.md.
• The live address and recording address interfaces use the unified response structure; see device-auth-address.md.