# Trax Public API > REST API for fleet-telematics data — devices, drivers, trips, safety events, rules, zones, groups, faults, maintenance, diagnostics, products, dispatch jobs, and aggregated driver/vehicle summaries. Every entity supports read (list/query/get) access; a defined set of resources — products, zones, groups, forms, maintenance requests, repair orders, devices, drivers, and dispatch jobs — also support create/update and entity-specific writes (e.g. deactivate, cancel), each gated by its own `:write` scope. JSON with snake_case keys, OAuth 2.0 client-credentials auth, tenant-scoped by the token's `company_id`. Every listing entity also exposes a `POST .../query` for structured per-field filtering. Conventions shared by every endpoint: - **Base URL**: `https://trax-public-api.zendu.one/v1` (local: `http://localhost:1500/v1`). - **Auth**: OAuth 2.0 client-credentials. Exchange your `client_id`/`client_secret` for a bearer token, then send `Authorization: Bearer ` on every request. The token is tenant-scoped by its `company_id`; scopes are per-resource (e.g. `devices:read`). The optional space-separated `scope` narrows the token (omit → all scopes granted to the client; unknown scope → `400 invalid_scope`). Tokens last `expires_in` seconds (1 hour) — cache and reuse until expiry. ```bash curl -sS -X POST 'https://service-prod.zendu.one/Public/OAuth/Token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d grant_type=client_credentials \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET # → { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "..." } ``` - **Envelope**: success `{ "data": , "meta": { "request_id": ... } }`; error `{ "error": { "code", "message", "request_id" } }`. - **Rate limits**: per OAuth client (default 120 req/min). Over-limit returns `429` with `Retry-After` and `X-RateLimit-Limit`/`-Remaining`/`-Reset` headers. - **Lists**: cursor pagination — pass `meta.next_cursor` back as `?cursor=`; `?limit=` (default 100, max 1000); `meta.has_more` signals more pages. - **Shaping**: `?fields=` (CSV) adds optional fields to the default set; `?include=` (CSV) expands allow-listed relationships inline. Only allow-listed fields are ever returned — internal columns never leak. - **Dates**: ISO-8601 UTC. Most date ranges are capped at **31 days** (one calendar month) — a `from`/`to` span longer than 31 days is rejected (400); paginate longer ranges yourself. `faults` is the exception: its `from`/`to` are uncapped and optional, because a fault is long-lived state rather than an event, so omitting both bounds returns every matching fault instead of a default window. Date-windowed list endpoints (trips, safety-events, maintenance-requests, repair-orders, diagnostics, locations, ifta-summaries) default to the **last 30 days** when both bounds are omitted. Summaries take `?from=`/`?to=` (YYYY-MM-DD), default = yesterday, max 31-day span. ## API reference - [OpenAPI spec (YAML)](https://trax-public-api.zendu.one/docs/openapi.yaml): full machine-readable contract — 117 operations. - [OpenAPI spec (JSON)](https://trax-public-api.zendu.one/docs/openapi.json): the same contract as JSON. - [Swagger UI](https://trax-public-api.zendu.one/docs/): browse and try every endpoint in the browser. - [Field-level reference](https://trax-public-api.zendu.one/docs/llms-full.txt): every entity's default/optional fields, filters and expandable relationships. ## Endpoints - [Devices](https://trax-public-api.zendu.one/v1/devices): Vehicles and trackers (identity, status, group membership); live position via the status sub-resource. (GET /devices, POST /devices/query, GET /devices/{id}, GET /devices/{id}/status, POST /devices, PATCH /devices/{id}; scopes `devices:read` (read), `devices:write` (write)) - [Drivers](https://trax-public-api.zendu.one/v1/drivers): Drivers (from the users collection); credentials and security state are never exposed. (GET /drivers, POST /drivers/query, GET /drivers/{id}, POST /drivers, PATCH /drivers/{id}, DELETE /drivers/{id}; scopes `drivers:read` (read), `drivers:write` (write)) - [Trips](https://trax-public-api.zendu.one/v1/trips): Completed trips (distance, durations, speed), tenant-scoped through the owning device. (GET /trips, POST /trips/query, GET /trips/{id}; scope `trips:read`) - [Safety events](https://trax-public-api.zendu.one/v1/safety-events): Rule violations / safety exceptions with derived handling status. (GET /safety-events, POST /safety-events/query, GET /safety-events/{id}; scope `safety:read`) - [Rules](https://trax-public-api.zendu.one/v1/rules): Safety rule definitions. (GET /rules, POST /rules/query, GET /rules/{id}; scope `rules:read`) - [Zones](https://trax-public-api.zendu.one/v1/zones): Geofences / zones. (GET /zones, POST /zones/query, GET /zones/{id}, POST /zones, PATCH /zones/{id}, DELETE /zones/{id}; scopes `zones:read` (read), `zones:write` (write)) - [Groups](https://trax-public-api.zendu.one/v1/groups): The group hierarchy used to scope and filter every other entity. (GET /groups, POST /groups/query, GET /groups/{id}, POST /groups, PATCH /groups/{id}, DELETE /groups/{id}; scopes `groups:read` (read), `groups:write` (write)) - [Faults](https://trax-public-api.zendu.one/v1/faults): Detected vehicle faults with triage state, one row per fault raised on a device, scoped to the token's company. Status is one of New, Triaged, Assigned, WorkOrder, Active, Dismissed, Closed. The shared code catalog is embeddable via `include=insight`. (GET /faults, POST /faults/query, GET /faults/{id}; scope `faults:read`) - [Fault codes](https://trax-public-api.zendu.one/v1/fault-codes): Global, AI-enriched diagnostic-code catalog (shared reference data; no tenant scoping). (GET /fault-codes, POST /fault-codes/query, GET /fault-codes/{id}; scope `faults:read`) - [Maintenance](https://trax-public-api.zendu.one/v1/maintenance-requests): Vehicle maintenance service requests. (GET /maintenance-requests, POST /maintenance-requests/query, GET /maintenance-requests/{id}, POST /maintenance-requests, PATCH /maintenance-requests/{id}, DELETE /maintenance-requests/{id}; scopes `maintenance:read` (read), `maintenance:write` (write)) - [Maintenance](https://trax-public-api.zendu.one/v1/repair-orders): Repair orders (curated totals; raw cost breakdowns hidden). (GET /repair-orders, POST /repair-orders/query, GET /repair-orders/{id}, POST /repair-orders, PATCH /repair-orders/{id}, DELETE /repair-orders/{id}; scopes `maintenance:read` (read), `maintenance:write` (write)) - [Diagnostics](https://trax-public-api.zendu.one/v1/diagnostics): Sensor/telemetry time-series (list-only, date-cursored). (GET /diagnostics, POST /diagnostics/query; scope `diagnostics:read`) - [Locations](https://trax-public-api.zendu.one/v1/locations): Historical vehicle locations / breadcrumbs (list-only, date-cursored). (GET /locations, POST /locations/query; scope `locations:read`) - [Forms](https://trax-public-api.zendu.one/v1/forms): Company form definitions (layout, DVIR/safety config, reusability); notification routing details are never exposed. (GET /forms, POST /forms/query, GET /forms/{id}, DELETE /forms/{id}; scopes `forms:read` (read), `forms:write` (write)) - [Forms](https://trax-public-api.zendu.one/v1/form-submissions): Submitted forms (dispatch tasks carrying a completed form), list-only and date-cursored; raw layout is sanitized into `answers`. (GET /form-submissions, POST /form-submissions/query; scope `forms:read`) - [Forms](https://trax-public-api.zendu.one/v1/form-schedules): Scheduled form dispatches — one row per scheduled execution of a form on a device/driver. (GET /form-schedules, POST /form-schedules/query, GET /form-schedules/{id}; scope `forms:read`) - [Products](https://trax-public-api.zendu.one/v1/products): Marketplace/dispatch products (pricing, stock, zone/device association). (GET /products, POST /products/query, GET /products/{id}, POST /products, PATCH /products/{id}, DELETE /products/{id}; scopes `products:read` (read), `products:write` (write)) - [Jobs](https://trax-public-api.zendu.one/v1/jobs): Dispatch jobs (work orders) with stops, assignment and status. Update is metadata-only — stops/device/user/assignment-type are create-only and frozen after creation to avoid triggering dispatch-service ETA recompute, reassignment, or Order-sync. (GET /jobs, POST /jobs/query, GET /jobs/{id}, POST /jobs, PATCH /jobs/{id}, DELETE /jobs/{id}; scopes `jobs:read` (read), `jobs:write` (write)) - [Tracker types](https://trax-public-api.zendu.one/v1/tracker-types): Global device tracker-type catalog (device category, docs and support links; shared reference data, no tenant scoping). (GET /tracker-types, POST /tracker-types/query, GET /tracker-types/{id}; scope `devices:read`) - [Custom maps](https://trax-public-api.zendu.one/v1/custom-maps): Custom (Indoor/Web) map overlays for a company's locations, tenant-scoped. (GET /custom-maps, POST /custom-maps/query, GET /custom-maps/{id}; scope `maps:read`) - [Comments](https://trax-public-api.zendu.one/v1/comments): Comments attached to a parent entity (polymorphic ParentId, commonly a safety event), tenant-scoped, list-only, date-cursored. (GET /comments, POST /comments/query; scope `comments:read`) - [Users](https://trax-public-api.zendu.one/v1/users): All users (from the users collection, not just drivers; filter with `is_driver` to narrow); credentials and security state are never exposed. (GET /users, POST /users/query, GET /users/{id}, POST /users, PATCH /users/{id}, DELETE /users/{id}; scopes `users:read` (read), `users:write` (write)) - [Coaching sessions](https://trax-public-api.zendu.one/v1/coaching-sessions): Driver coaching deliveries (AI or manual): who was coached, when, on which safety events, and the delivery status. (GET /coaching-sessions, POST /coaching-sessions/query, GET /coaching-sessions/{id}; scope `coaching:read`) - [Driver summary](https://trax-public-api.zendu.one/v1/summaries/driver/{driverId}): aggregated per-driver rollup over a date range — trips, distance, exceptions, safety score. (GET /summaries/driver/{driverId}; scope `summaries:read`) - [Vehicle summary](https://trax-public-api.zendu.one/v1/summaries/vehicle/{deviceId}): aggregated per-vehicle rollup over a date range — distance, durations, odometer, drivers. (GET /summaries/vehicle/{deviceId}; scope `summaries:read`) - [IFTA summaries](https://trax-public-api.zendu.one/v1/ifta-summaries): distance by vehicle × jurisdiction × month, aggregated from trips. (GET /ifta-summaries; scope `ifta:read`) - [Form dispatches](https://trax-public-api.zendu.one/v1/form-dispatches): send ("dispatch") a form to drivers/groups — create-only action, not a CRUD entity; see Forms for the read side. (POST /form-dispatches; scope `forms:write`) - [Files](https://trax-public-api.zendu.one/v1/files): upload a file (multipart `file` field) to private storage and get an opaque id, then exchange the id for a short-lived signed download URL. Stored per-company; not publicly accessible. (POST /files; GET /files/{id}; scopes `files:write`, `files:read`) - [Media](https://trax-public-api.zendu.one/v1/media/video-requests): request camera video/snapshot clips (async, poll for the task result), get live/historical stream URLs, list recording segments, and wake a device. NOTE: /media/recordings is an INDEX of footage segments (no urls) — to RECEIVE recorded footage, take a segment's date_from and either watch it via /media/historical-streams (playable stream url) or download a clip via /media/video-requests. (POST /media/video-requests, POST /media/snapshot-requests, GET /media/tasks/{task_id}, POST /media/live-streams, POST /media/historical-streams, POST /media/recordings, POST /media/wake; scopes `media:write` (requests, wake), `media:read` (streams, recordings, task status)) - [Geocoding](https://trax-public-api.zendu.one/v1/geocoding/addresses): reverse-geocode coordinates to addresses plus the company's containing zone; the response array is parallel to the input coordinates. (POST /geocoding/addresses; scope `geocoding:read`) - [Text-to-Speech](https://trax-public-api.zendu.one/v1/tts/messages): send a text-to-speech audio message to StreamMax cameras (text ≤ 150 chars; language english or spanish); reports per-device success/failed. (POST /tts/messages; scope `tts:write`) - [Device driver assignment](https://trax-public-api.zendu.one/v1/devices/{id}/assign-driver): assign or remove drivers on a device — actions, not CRUD writes (`assigned_driver_id` is read-only on the device). (POST /devices/{id}/assign-driver, POST /devices/{id}/remove-driver; scope `devices:write`) - [Driver password reset](https://trax-public-api.zendu.one/v1/drivers/{id}/reset-password): reset a driver's password — an action, not a CRUD write (`password` on `drivers` is create-only + write-only). (POST /drivers/{id}/reset-password; scope `drivers:write`) - [Job actions](https://trax-public-api.zendu.one/v1/jobs/{id}/submit): submit a work order, assign a device, add/delete a stop — actions, not CRUD writes (they trigger dispatch-service side effects like ETA recompute; `stops`/`device_id` are frozen on the `jobs` entity's own update). (POST /jobs/{id}/submit, POST /jobs/{id}/assign-device, POST /jobs/{id}/stops, DELETE /jobs/{id}/stops/{stopId}; scope `jobs:write`) - [Repair order status change](https://trax-public-api.zendu.one/v1/repair-orders/{id}/status): change a repair order's status — an action, not a CRUD write. (POST /repair-orders/{id}/status; scope `maintenance:write`)