¶ ZECTRIX Cloud API Documentation

The API documentation on this page may not always be up to date. For the latest API documentation, visit:
https://cloud.zectrix.com/home/api-docs

¶ Authentication

API requests must include authentication information in the header:

Authorization: Bearer <token>

Alternatively, use an API Key:

X-API-Key: <api_key>

¶ Basic Information

API Base URL: https://cloud.zectrix.com
API Version Prefix: /open/v1/
API Key: zt_xxx

¶ 1. Device Management

¶ Get Device List

Method: GET
URL: https://cloud.zectrix.com/open/v1/devices

Response Example:

{
  "code": 0,
  "data": [
    {
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "alias": "My Device",
      "board": "bread-compact-wifi"
    }
  ]
}

curl Example:

curl "https://cloud.zectrix.com/open/v1/devices" \
  -H "X-API-Key: zt_xxx"

¶ 2. To-Dos

¶ Get To-Do List

Method: GET
URL: https://cloud.zectrix.com/open/v1/todos

Parameters:

Parameter	Type	Description
status	integer	Filter by status: 0=pending, 1=completed
deviceId	string	Device ID (MAC address); filters by device

Response Example:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "title": "Buy milk",
      "description": "",
      "dueDate": "2026-03-20",
      "dueTime": "09:00",
      "repeatType": "none",
      "status": 0,
      "priority": 1,
      "completed": false,
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "deviceName": "My Device",
      "createDate": "2026-03-18 10:00:00",
      "updateDate": 1742284800
    }
  ]
}

¶ Create a To-Do

Method: POST
URL: https://cloud.zectrix.com/open/v1/todos

Request Body:

{
  "title": "Buy milk",
  "description": "",
  "dueDate": "2026-03-20",
  "dueTime": "09:00",
  "repeatType": "none",
  "priority": 1,
  "deviceId": "AA:BB:CC:DD:EE:FF"
}

Request Body Parameters:

Parameter	Type	Required	Description
title	string	Yes	To-do title
description	string	No	To-do description
dueDate	string	No	Due date in YYYY-MM-DD format
dueTime	string	No	Due time in HH:mm format
repeatType	string	No	Repeat type; defaults to "none"
priority	integer	No	Priority
deviceId	string	No	Associated device ID

Response Example:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "Buy milk",
    "status": 0,
    "priority": 1,
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "createDate": "2026-03-18 10:00:00"
  }
}

¶ Update a To-Do

Method: PUT
URL: https://cloud.zectrix.com/open/v1/todos/{id}

Path Parameters:

Parameter	Type	Description
id	integer	To-do ID

Request Body Example:

{
  "title": "Buy milk and bread"
}

Updatable Request Body Fields:

Parameter	Type	Description
title	string	To-do title
description	string	To-do description
dueDate	string	Due date
dueTime	string	Due time
repeatType	string	Repeat type
priority	integer	Priority
deviceId	string	Associated device ID

Response Example:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "Buy milk and bread",
    "status": 0,
    "priority": 1
  }
}

¶ Mark Complete / Mark Incomplete

Method: PUT
URL: https://cloud.zectrix.com/open/v1/todos/{id}/complete

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	To-do ID

Response Example:

{
  "code": 0,
  "msg": "success"
}

¶ Delete a To-Do

Method: DELETE
URL: https://cloud.zectrix.com/open/v1/todos/{id}

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	To-do ID

Response Example:

{
  "code": 0,
  "msg": "success"
}

¶ 3. Display Push

¶ Push Images to a Device

Method: POST
URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/image

Path Parameters:

Parameter	Type	Required	Description
deviceId	string	Yes	Device ID (MAC address)

Request Parameters:

Parameter	Type	Required	Description
images	file	Yes	Image files; supports up to five images, with a maximum of 2 MB per image
dither	boolean	No	Whether to use dithering (default: true); false uses hard-threshold binarization
pageId	string	No	Page number (1–5); specifying it enables persistent storage

Response Example:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

¶ Push Text to a Device

Method: POST
URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/text

Path Parameters:

Parameter	Type	Required	Description
deviceId	string	Yes	Device ID (MAC address)

Request Body:

Parameter	Type	Required	Description
text	string	Yes	Text content; supports `\n` line breaks
fontSize	integer	No	Font size
pageId	string	No	Page number (1–5)

Request Body Example:

{
  "text": "Today's weather: Sunny\\nTemperature: 25°C",
  "fontSize": 20,
  "pageId": "1"
}

Response Example:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

¶ Push a Title and Body to a Device

Method: POST
URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/structured-text

Path Parameters:

Parameter	Type	Required	Description
deviceId	string	Yes	Device ID (MAC address)

Request Body:

Parameter	Type	Required	Description
title	string	Yes	Title
body	string	Yes	Body text; supports `\n` line breaks
pageId	string	No	Page number (1–5)

Request Body Example:

{
  "title": "Meeting Reminder",
  "body": "3:00 PM, third-floor conference room\\nPlease bring your laptop",
  "pageId": "1"
}

Response Example:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

¶ Delete a Page

Method: DELETE
URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/pages/{pageId}

Path Parameters:

Parameter	Type	Required	Description
deviceId	string	Yes	Device ID (MAC address)
pageId	string	No	Page number; omit it to delete all pages

Response Example:

{
  "code": 0,
  "msg": "success"
}

¶ Error Codes

code	Meaning
0	Success
Other	Error (see the specific error message)

Documentation retrieved: 2026-04-09