Devices: basics, track
4 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.
A device's track is under /v1/devices/{deviceId}/track and the vehicle it is bound to under /v1/devices/{deviceId}/vehicle; both are listed on Positions and Vehicles.
Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.
Bind a device to an asset
POST /v1/devices/{id}:bind
- Scope:
devices:writeordevices:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: low risk
- Step-up MFA: no
Path parameters: id.
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
kind | string | |
targetId | string |
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | string | |
tenantId | string | |
externalId | string | |
name | string | omitted when empty |
model | string | |
manufacturer | string | |
makerId | string | omitted when empty |
modelId | string | omitted when empty |
codecId | string | |
deviceClass | string | |
status | string | |
firmwareVersion | string | omitted when empty |
capabilities | array of string | omitted when empty |
hasCommandPassword | boolean | |
sim | object | omitted when empty |
sim.iccid | string | omitted when empty |
sim.msisdn | string | omitted when empty |
sim.operator | string | omitted when empty |
sim.apn | string | omitted when empty |
sim.status | string | omitted when empty |
reportedFirmware | string | omitted when empty |
firmwareReportedAt | string | omitted when empty |
portable | boolean | |
boundTo | object | omitted when empty |
boundTo.kind | string | |
boundTo.targetId | string | |
boundTo.boundAt | string | |
createdAt | string | |
updatedAt | string | |
version | integer |
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/devices/$ID:bind" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"kind": "…", "targetId": "…"}'
Unbind a device
POST /v1/devices/{id}:unbind
- Scope:
devices:writeordevices:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: low risk
- Step-up MFA: no
Path parameters: id.
Request
No body: the handler reads none.
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Bind a device to an asset.
Example
curl -X POST "https://api.zaitrack.app/v1/devices/$ID:unbind" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)"
Retire a device
POST /v1/devices/{id}:retire
- Scope:
devices:writeordevices:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: medium risk
- Step-up MFA: no
Path parameters: id.
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
reason | string |
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Bind a device to an asset.
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/devices/$ID:retire" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'
A device's positions (?from=&to=&limit=)
GET /v1/devices/{deviceId}/track
- Scope:
telemetry:readortelemetry:* - Rate class:
telemetry(10 per second and 180,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
Path parameters: deviceId.
| Query parameter | Type | Notes |
|---|---|---|
from | string | |
to | string | |
limit | string |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
deviceId | — | |
from | — | |
to | — | |
points | array of object | |
points[].deviceId | string | |
points[].occurredAt | string (date-time) | |
points[].lat | number | |
points[].lon | number | |
points[].speedKph | number | may be null |
points[].headingDeg | number | may be null |
points[].ignition | boolean | may be null |
truncated | — |
Example
curl "https://api.zaitrack.app/v1/devices/$DEVICE_ID/track" \
-H "Authorization: Bearer zk_test_…"