Skip to main content

Vehicles: basics

6 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.

List vehicles​

GET /v1/vehicles

  • Scope: vehicles:read or vehicles:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
subOrgIdstring
assetClassstring
statusstring
regionstring
primaryDriverIdstring
platestring
cursorstring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].idstring
items[].tenantIdstring
items[].subOrgIdstringomitted when empty
items[].vinstringomitted when empty
items[].registrationobjectomitted when empty
items[].registration.countrystring
items[].registration.platestring
items[].makestring
items[].modelstring
items[].yearinteger
items[].assetClassstring
items[].statusstring
items[].capabilitiesarray of string
items[].currentRegionstringomitted when empty
items[].odometerKminteger
items[].capacityTonsnumber
items[].fuelTypestring
items[].primaryDriverIdstringomitted when empty
items[].attachedDevicesarray of string
items[].markerIconstring
items[].markerIconSetboolean
items[].speedLimitKphintegermay be null
items[].createdAtstring
items[].updatedAtstring
items[].versioninteger
items[].etagstring
nextCursorstring

Example​

curl "https://api.zaitrack.app/v1/vehicles" \
-H "Authorization: Bearer zk_test_…"

Create a vehicle​

POST /v1/vehicles

  • Scope: vehicles:write or vehicles:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: no
  • Step-up MFA: no

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
subOrgIdstringoptional
vinstringoptional
registrationobjectoptional
registration.countrystring
registration.platestring
makestring
modelstring
yearinteger
assetClassstring
capabilitiesarray of stringoptional
currentRegionstringoptional
odometerKminteger
capacityTonsnumber
fuelTypestring
markerIconstringoptional
speedLimitKphintegeroptional

Response​

201: fields the handler writes, taken from its source.

FieldTypeNotes
idstring
tenantIdstring
subOrgIdstringomitted when empty
vinstringomitted when empty
registrationobjectomitted when empty
registration.countrystring
registration.platestring
makestring
modelstring
yearinteger
assetClassstring
statusstring
capabilitiesarray of string
currentRegionstringomitted when empty
odometerKminteger
capacityTonsnumber
fuelTypestring
primaryDriverIdstringomitted when empty
attachedDevicesarray of string
markerIconstring
markerIconSetboolean
speedLimitKphintegermay be null
createdAtstring
updatedAtstring
versioninteger
etagstring

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/vehicles" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"subOrgId": "…", "vin": "…", "registration": {"country": "…", "plate": "…"}, "make": "…", "model": "…", "year": 0, "assetClass": "…", "capabilities": [], "currentRegion": "…", "odometerKm": 0, "capacityTons": 0, "fuelType": "…", "markerIcon": "…", "speedLimitKph": 0}'

Get a vehicle​

GET /v1/vehicles/{id}

  • Scope: vehicles:read or vehicles:*
  • 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.

The same fields as the response of Create a vehicle.

Example​

curl "https://api.zaitrack.app/v1/vehicles/$ID" \
-H "Authorization: Bearer zk_test_…"

Update a vehicle (If-Match version)​

PATCH /v1/vehicles/{id}

  • Scope: vehicles:write or vehicles:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • 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.

FieldTypeNotes
registrationobjectoptional
registration.countrystring
registration.platestring
makestringoptional
modelstringoptional
yearintegeroptional
capabilitiesarray of stringoptional
odometerKmintegeroptional
capacityTonsnumberoptional
fuelTypestringoptional
currentRegionstringoptional
subOrgIdstringoptional
markerIconstringoptional
speedLimitKphobject
speedLimitKph.Setboolean
speedLimitKph.Valueintegeroptional

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Create a vehicle.

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/vehicles/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"registration": {"country": "…", "plate": "…"}, "make": "…"}'

Decommission a vehicle​

POST /v1/vehicles/{id}:decommission

  • Scope: vehicles:write or vehicles:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: medium 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.

FieldTypeNotes
reasonstring

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Create a vehicle.

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:decommission" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'

Reactivate a decommissioned vehicle​

POST /v1/vehicles/{id}:reactivate

  • Scope: vehicles:write or vehicles:*
  • 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​

No body: the handler reads none.

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Create a vehicle.

Example​

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:reactivate" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)"