Skip to main content

Maintenance: plans, vehicles

9 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 service plans​

GET /v1/maintenance/plans

  • Scope: maintenance:read or maintenance:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Request​

No body.

Response​

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

FieldTypeNotes
itemsarray of object
items[].idstring
items[].namestring
items[].descriptionstring
items[].intervalKminteger
items[].intervalHoursinteger
items[].intervalDaysinteger
items[].remindKminteger
items[].remindHoursinteger
items[].remindDaysinteger
items[].tasksarray of string
items[].vehicleIdsarray of string
items[].autoWorkOrderboolean
items[].enabledboolean
items[].createdBystring
items[].createdAtstring
items[].updatedAtstring
items[].versioninteger

Example​

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

Create a service plan​

POST /v1/maintenance/plans

  • Scope: maintenance:write or maintenance:*
  • 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
namestringoptional
descriptionstringoptional
intervalKmintegeroptional
intervalHoursintegeroptional
intervalDaysintegeroptional
remindKmintegeroptional
remindHoursintegeroptional
remindDaysintegeroptional
tasksarray of stringoptional
vehicleIdsarray of stringoptional
autoWorkOrderbooleanoptional
enabledbooleanoptional

Response​

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

FieldTypeNotes
idstring
namestring
descriptionstring
intervalKminteger
intervalHoursinteger
intervalDaysinteger
remindKminteger
remindHoursinteger
remindDaysinteger
tasksarray of string
vehicleIdsarray of string
autoWorkOrderboolean
enabledboolean
createdBystring
createdAtstring
updatedAtstring
versioninteger

Example​

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

curl -X POST "https://api.zaitrack.app/v1/maintenance/plans" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name": "…", "description": "…", "intervalKm": 0, "intervalHours": 0, "intervalDays": 0, "remindKm": 0, "remindHours": 0, "remindDays": 0, "tasks": [], "vehicleIds": [], "autoWorkOrder": false, "enabled": false}'

Get a service plan​

GET /v1/maintenance/plans/{id}

  • Scope: maintenance:read or maintenance:*
  • 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 service plan.

Example​

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

Update a service plan​

PATCH /v1/maintenance/plans/{id}

  • Scope: maintenance:write or maintenance:*
  • 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.

The same fields as the request of Create a service plan.

Response​

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

The same fields as the response of Create a service plan.

Example​

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

curl -X PATCH "https://api.zaitrack.app/v1/maintenance/plans/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"name": "…", "description": "…"}'

Delete a service plan​

DELETE /v1/maintenance/plans/{id}

  • Scope: maintenance:write or maintenance:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: low risk
  • Step-up MFA: no

Path parameters: id.

Request​

No body.

Response​

204: no body.

Example​

curl -X DELETE "https://api.zaitrack.app/v1/maintenance/plans/$ID" \
-H "Authorization: Bearer zk_test_…"

Record a service done on a vehicle​

PUT /v1/maintenance/plans/{id}/vehicles/{vehicleId}

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

Path parameters: id, vehicleId.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
lastServiceAtstringoptional
lastServiceKmnumberoptional
lastServiceHoursnumberoptional

Response​

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

FieldTypeNotes
planId—
planName—
vehicleId—
status—
statusSincestring
lastDoneAtstring
lastDoneKm—
lastDoneHours—
nextDueAt—
nextDueKm—
nextDueHours—
openWorkOrderId—

Example​

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

curl -X PUT "https://api.zaitrack.app/v1/maintenance/plans/$ID/vehicles/$VEHICLE_ID" \
-H "Authorization: Bearer zk_test_…" \
-H "Content-Type: application/json" \
-d '{"lastServiceAt": "…", "lastServiceKm": 0, "lastServiceHours": 0}'

A vehicle's plans and their state​

GET /v1/maintenance/vehicles/{vehicleId}

  • Scope: maintenance:read or maintenance:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: vehicleId.

Request​

No body.

Response​

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

FieldTypeNotes
vehicleId—
meterobject
meter.odometerKm—
meter.engineHours—
meter.readAtstring
meter.source—
plansarray of object
plans[].planId—
plans[].planName—
plans[].vehicleId—
plans[].status—
plans[].statusSincestring
plans[].lastDoneAtstring
plans[].lastDoneKm—
plans[].lastDoneHours—
plans[].nextDueAt—
plans[].nextDueKm—
plans[].nextDueHours—
plans[].openWorkOrderId—

Example​

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

Report an odometer or engine-hours reading​

POST /v1/maintenance/vehicles/{vehicleId}/meter

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

Path parameters: vehicleId.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
odometerKmnumberoptional
engineHoursnumberoptional
readAtstringoptional
correctionboolean

Response​

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

FieldTypeNotes
odometerKm—
engineHours—
readAtstring
source—

Example​

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

curl -X POST "https://api.zaitrack.app/v1/maintenance/vehicles/$VEHICLE_ID/meter" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"odometerKm": 0, "engineHours": 0, "readAt": "…", "correction": false}'

Whether a vehicle may be driven​

GET /v1/maintenance/vehicles/{vehicleId}/roadworthiness

  • Scope: maintenance:read or maintenance:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: vehicleId.

Request​

No body.

Response​

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

FieldTypeNotes
vehicleId—
safeToOperateboolean
blocking—
openDefects—

Example​

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