ZECTRIX Cloud API Documentation

Synced with the Cloud API documentation on 2026-10-13. Refer to the cloud documentation for subsequent updates.

Get an API Key

  1. Open ZECTRIX Cloud and choose QR-code login.
  2. In the mini program, go to Me → Scan to log in to the platform and scan the QR code.
  3. Open Open API (开放API) in the platform menu, then choose Create API Key (创建 API Key).
  4. Follow the on-screen instructions and keep your API Key private. Do not publish it or commit it to a public repository.

Authentication

The current cloud documentation uses the following request header for the public /open/v1/ endpoints:

X-API-Key: zt_your_key_here

Send JSON request bodies with Content-Type: application/json. Image uploads use multipart/form-data; let your HTTP client generate the boundary.

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"

Update Sync Interval

  • Method: PUT
  • URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/sync-interval
Parameter Location Type Required Description
deviceId Path string Yes Device ID (MAC address)
syncInterval JSON body integer Yes Interval in minutes. Only 0 (disabled), 10, 30, 60, 180, and 720 are allowed.

curl Example:

curl -X PUT "https://cloud.zectrix.com/open/v1/devices/AA:BB:CC:DD:EE:FF/sync-interval" \
  -H "X-API-Key: zt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"syncInterval":60}'

Response Example:

{
  "code": 0,
  "msg": "success",
  "data": {
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "syncInterval": 60
  }
}

2. To-Dos

Get To-Do List

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

Parameters:

Parameter Type Required Description
status integer No Filter: 0 = pending, 1 = completed
deviceId string No Device ID (MAC address); filter 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 Description
dueDate string No Due date: yyyy-MM-dd
dueTime string No Due time: HH:mm
repeatType string No daily / weekly / monthly / yearly / none
repeatWeekday integer No 0–6; 0 = Sunday (weekly)
repeatMonth integer No 1–12 (yearly)
repeatDay integer No 1–31 (monthly/yearly)
priority integer No 0 = normal, 1 = important, 2 = urgent
deviceId string No Device ID (MAC address); empty means a personal to-do

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 Required Description
title string No To-do title
description string No Description
dueDate string No Due date: yyyy-MM-dd
dueTime string No Due time: HH:mm
priority integer No 0 = normal, 1 = important, 2 = urgent

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 (multipart/form-data):

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 Up to 5,000 characters; supports line breaks
fontSize integer No 12–48; default: 20
pageId string No Page number (1–5); specifying it enables persistent storage

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 No Up to 200 characters; provide at least one of title or body
body string No Up to 5,000 characters; supports line breaks; provide at least one of title or body
pageId string No Page number (1–5); specifying it enables persistent storage

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)

Last synchronized: 2026-10-13