Contoh alur lengkap

Skenario dari nol memakai curl. Sebelumnya, atur variabel dari Pengantar API: CELESTIAN, TOKEN, dan WS. Respons di bawah diambil dari backend yang berjalan (ID dipendekkan; <...> = isi sendiri).

1. Cek token dan workspace

curl -s "$CELESTIAN/api/v1/workspaces/$WS" -H "Authorization: Bearer $TOKEN"

{ "workspace": { "id": "…", "name": "Gudang Dingin Nusantara", "route": "gudang-nusantara", "status": "enabled", "tags": ["contoh"] },
  "permissions": ["workspace.read", "device.read", "device.write", "channel.write", "rule.write", "…"],
  "memberCount": 1, "owner": { "id": "…", "username": "…" }, "isOwner": true, "pendingTransfer": null }

permissions adalah hak efektif token ini. Periksa bila sebuah aksi ditolak.

2. Buat channel

curl -s -X POST "$CELESTIAN/api/v1/workspaces/$WS/channels" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"Telemetri Gudang","route":"telemetri-gudang","tags":["telemetri"]}'

201 → {"channel": {"id": "<channel-id>", "name": "Telemetri Gudang", "route": "telemetri-gudang", "status": "enabled", …}}. route opsional (huruf kecil, angka, -).

3. Buat device dan simpan key-nya

curl -s -X POST "$CELESTIAN/api/v1/workspaces/$WS/devices" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"Sensor Ruang Beku A1","serial":"SN-A1","tags":["ruang-beku"]}'

{ "device": { "id": "<device-id>", "name": "Sensor Ruang Beku A1", "serial": "SN-A1", "isGateway": false,
              "status": "enabled", "keyRotatedAt": "…", "tags": ["ruang-beku"] },
  "key": "BVZvgFsU…" }

key hanya tampil sekali. Ini password MQTT device. Buat ulang dengan POST .../devices/{id}/key (badan {} untuk key acak, atau {"key": "<nilai-sendiri>"}). Kirim "isGateway": true untuk membuat gateway.

4. Izinkan device mengirim ke channel

curl -s -X POST "$CELESTIAN/api/v1/workspaces/$WS/connections" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deviceIds":["<device-id>"],"channelIds":["<channel-id>"],"types":["publish"]}'

204. types: publish (device mengirim) dan/atau subscribe (device menerima). Dibutuhkan device.connect dan channel.connect, maksimal 100 pasangan per permintaan. Putuskan dengan POST .../connections/disconnect (badan sama).

5. Pasang rule penyimpanan

curl -s -X POST "$CELESTIAN/api/v1/workspaces/$WS/rules/quick-store" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"channelId":"<channel-id>","format":"senml"}'

201 → rule Channel Subscriber (semua subtopik) → Bypass → Internal DB (SenML). format: senml (metrik angka, boolean, teks; mendukung nilai terakhir, agregasi, dan grafik) atau json (payload bebas). 409 bila channel itu sudah punya rule penyimpanan aktif.

6. Device mengirim data

mosquitto_pub -h <broker> -p 1883 -V mqttv311 -i <device-id> -u <device-id> -P '<key>' \
  -t "m/$WS/c/telemetri-gudang/ruang-a1" \
  -m '[{"bn":"ruang-a1:","n":"temp_inlet","u":"Cel","v":23.5},{"n":"humidity","u":"%RH","v":41.2},{"n":"door_open","vb":false}]'

7. Baca pesan

curl -s "$CELESTIAN/api/v1/workspaces/$WS/messages?channelId=<channel-id>&format=senml&limit=3" \
  -H "Authorization: Bearer $TOKEN"

{ "page": {
    "format": "senml",
    "senml": [
      { "time": "2026-10-02T22:42:05.432+07:00", "publisher": "<device-id>", "deviceId": "ruang-a1:",
        "subtopic": "ruang-a1", "protocol": "mqtt", "name": "ruang-a1:humidity", "unit": "%RH",
        "value": 41.2, "stringValue": null, "boolValue": null, "dataValue": null, "sum": null, "updateTime": null }
    ],
    "nextCursor": "MjAyNi0xMC0wMlQx…", "from": "2026-09-25T15:42:24Z", "to": null } }

Tanpa from dan to, yang ditampilkan 7 hari terakhir. Filter lain: subtopic, publisher, deviceId, name, protocol, valueOp (eq|ne|gt|gte|lt|lte) dengan valueNum dan valueType, dan sort=asc|desc. publisher adalah ID device pengirim yang terautentikasi, bukan dari isi payload.

8. Nama metrik, agregasi, dan status device

curl -s "$CELESTIAN/api/v1/workspaces/$WS/messages/names?channelId=<channel-id>" -H "Authorization: Bearer $TOKEN"
# {"names": ["ruang-a1:humidity", "ruang-a1:temp_inlet"]}

curl -s "$CELESTIAN/api/v1/workspaces/$WS/messages/aggregate?channelId=<channel-id>&name=ruang-a1:temp_inlet&interval=1h" \
  -H "Authorization: Bearer $TOKEN"
# {"interval":"1h","buckets":[{"time":"2026-10-02T22:00:00+07:00","name":"ruang-a1:temp_inlet","min":23.5,"max":23.5,"avg":23.5,"sum":47,"count":2}],"truncated":false,"from":"…"}

curl -s "$CELESTIAN/api/v1/workspaces/$WS/presence/devices?ids=<device-id>" -H "Authorization: Bearer $TOKEN"
# {"health": {"<device-id>": {"online": false, "clients": 0, "lastConnectAt": "…", "lastDisconnectAt": "…", "protocol": "mqtt"}},
#  "presence": {"<device-id>": {"lastSeen": "…", "protocol": "mqtt"}}}

interval: 1m, 5m, 15m, 1h, 6h, 1d. Ekspor CSV (maksimal 50.000 baris): GET .../messages/export.csv dengan filter yang sama.

9. Mengirim pesan ke channel dari API

Butuh channel.publish.

curl -s -X POST "$CELESTIAN/api/v1/workspaces/$WS/messages/send" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelId":"<channel-id>","subtopic":"ruang-a1","payload":"[{\"n\":\"temp_inlet\",\"u\":\"Cel\",\"v\":24.1}]"}'

204. payload berupa string (isi pesan apa adanya, maksimal 256 KB). Pesan tercatat berprotokol ui dan diproses rule seperti pesan device. Opsional "form": "uuid" | "route" memilih bentuk topik tujuan (broker mencocokkan topik secara literal).

10. Membuat dashboard dan rule

Dashboard dan rule adalah dokumen JSON yang sama dengan yang diunduh dari aplikasi. Cara termudah mempelajarinya: buat satu lewat UI, lalu GET dan ubah.

# daftar dashboard (tanpa widget)
curl -s "$CELESTIAN/api/v1/workspaces/$WS/dashboards" -H "Authorization: Bearer $TOKEN"
# satu rule beserta graf
curl -s "$CELESTIAN/api/v1/workspaces/$WS/rules/<rule-id>" -H "Authorization: Bearer $TOKEN"