Vehicles: basics, devices, drivers, status history
7 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.
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.
Put a vehicle in service mode
POST /v1/vehicles/{id}:service
- Scope:
vehicles:writeorvehicles:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
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.
| Field | Type | Notes |
|---|---|---|
id | string | |
tenantId | string | |
subOrgId | string | omitted when empty |
vin | string | omitted when empty |
registration | object | omitted when empty |
registration.country | string | |
registration.plate | string | |
make | string | |
model | string | |
year | integer | |
assetClass | string | |
status | string | |
capabilities | array of string | |
currentRegion | string | omitted when empty |
odometerKm | integer | |
capacityTons | number | |
fuelType | string | |
primaryDriverId | string | omitted when empty |
attachedDevices | array of string | |
markerIcon | string | |
markerIconSet | boolean | |
speedLimitKph | integer | may be null |
createdAt | string | |
updatedAt | string | |
version | integer | |
etag | string |
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:service" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'
Return a vehicle to normal mode
POST /v1/vehicles/{id}:normal
- Scope:
vehicles:writeorvehicles:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id.
Request
Fields the handler reads, taken from its source.
The same fields as the request of Put a vehicle in service mode.
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Put a vehicle in service mode.
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:normal" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'
Devices bound to a vehicle
GET /v1/vehicles/{id}/devices
- Scope:
vehicles:readorvehicles:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
Path parameters: id.
Request
No body.
Response
200: fields the handler writes, taken from its source.
Keys: items. Their types are not described.
Example
curl "https://api.zaitrack.app/v1/vehicles/$ID/devices" \
-H "Authorization: Bearer zk_test_…"
Bind a device to a vehicle
POST /v1/vehicles/{id}/devices
- Scope:
vehicles:writeorvehicles:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: low risk
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id.
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
deviceId | string |
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Put a vehicle in service mode.
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID/devices" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"deviceId": "…"}'
Unbind a device from a vehicle
DELETE /v1/vehicles/{id}/devices/{deviceId}
- Scope:
vehicles:writeorvehicles:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: not used
- Audited: low risk
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id, deviceId.
Request
No body.
Response
204: no body.
Example
curl -X DELETE "https://api.zaitrack.app/v1/vehicles/$ID/devices/$DEVICE_ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"'
Assign a driver to a vehicle
POST /v1/vehicles/{id}/drivers
- Scope:
vehicles:writeorvehicles:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id.
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
driverId | string |
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Put a vehicle in service mode.
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID/drivers" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"driverId": "…"}'
Vehicle status changes over a period
GET /v1/vehicles/status-history
- Scope:
vehicles:readorvehicles:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
| Query parameter | Type | Notes |
|---|---|---|
vehicleId | string | |
from | — | |
to | — |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].vehicleId | — | |
items[].status | — | |
items[].reason | — | |
items[].actor | — | |
items[].at | — |
Example
curl "https://api.zaitrack.app/v1/vehicles/status-history" \
-H "Authorization: Bearer zk_test_…"