REST API
Endpoint reference
All paths are relative to https://safartrack-backend.safartrak.com/api/v1/external. Authenticate every request as described in getting started.
Vehicles & live location
Current fleet state, live positions and the full route a vehicle drove.
| Method | Path | What it returns |
|---|---|---|
| GET | /vehicles | List vehicles with their current status. Filter with search, status, vehicleType, vehicleCategory and fleetGroup; paginate with page and limit. |
| GET | /vehicles/summary | Fleet status counts (moving, idle, stopped, offline) using the same filters as /vehicles. |
| GET | /vehicles/{uniqueId} | One vehicle's current details and latest reading. |
| GET | /vehicles/{uniqueId}/route-history | Route history for a vehicle. Use period (default today) or a from and to range; add snap to align the path to roads. |
| GET | /locations | Live location feed for the vehicles in your account. |
Temperature (cold chain)
Readings from compatible temperature sensors.
| Method | Path | What it returns |
|---|---|---|
| GET | /temperature | Current temperature status across sensor-equipped vehicles. |
| GET | /temperature/{uniqueId}/history | Temperature history for one vehicle over a date range. |
Alerts & driver events
Speeding, idling, geofence and other configured events.
| Method | Path | What it returns |
|---|---|---|
| GET | /alerts | List alerts, newest first, with filters and pagination. |
| GET | /alerts/count | Number of alerts matching your filters. |
| GET | /alerts/summary | Alert totals grouped by type. |
| GET | /alerts/types | The alert types available for your account. |
| GET | /alerts/export | Download matching alerts as CSV. |
Analytics & reports
Distance, performance and fleet-level reporting.
| Method | Path | What it returns |
|---|---|---|
| GET | /analytics/summary | Fleet analytics summary for the selected range. |
| GET | /analytics/distance-series | Distance travelled over time, for charts and BI tools. |
| GET | /analytics/performance | Vehicle performance metrics for the selected range. |
| GET | /analytics/export | Export analytics as JSON. |
Utilisation & vendors
Kilometre and hour utilisation by vehicle, vendor and city.
| Method | Path | What it returns |
|---|---|---|
| GET | /utilisation/summary | Utilisation overview for a date range. |
| GET | /utilisation/vehicles | Per-vehicle utilisation, filterable by city, vendor, vehicle type and utilisation band. |
| GET | /utilisation/vendors | Utilisation grouped by vendor; /utilisation/vendors/{vendorId} for one vendor. |
| GET | /utilisation/matrix | Utilisation matrix for planning and comparison. |
| GET | /utilisation/alerts | Under- and over-utilisation flags. |
| GET | /utilisation/reuse | Reuse opportunities for under-used vehicles. |
Trip schedules
Create, update and track planned trips and checkpoints.
| Method | Path | What it returns |
|---|---|---|
| GET | /trip-schedules | List trip schedules; /trip-schedules/summary for totals. |
| POST | /trip-schedules | Create a trip schedule with its checkpoints. |
| GET | /trip-schedules/{tripId} | One trip schedule and its progress. |
| PATCH | /trip-schedules/{tripId} | Update a trip schedule. |
| DELETE | /trip-schedules/{tripId} | Remove a trip schedule. |
| GET | /trip-schedules/template-csv | Download the CSV template for bulk upload. |
| POST | /trip-schedules/bulk-upload | Upload many trip schedules from a CSV file (multipart form). |
Reference data
Lists you can use to build filters and forms.
| Method | Path | What it returns |
|---|---|---|
| GET | /vehicle-types | Vehicle types in your account. |
| GET | /vehicle-categories | Vehicle categories. |
| GET | /fleet-groups | Fleet groups. |
| GET | /vendors | Vendors; /vendors/cities for the cities they operate in. |
| GET | /associated-clients | Associated client accounts you can access. |
Responses & errors
Every successful response includes success: true. Errors return success: false and a message:
{
"success": false,
"message": "Invalid API key or API secret."
}| Status | Meaning |
|---|---|
| 200 | Success. The body contains success: true and the requested data. |
| 401 | The API key or secret is missing or invalid. |
| 403 | The credentials are valid but the account is inactive or cannot access this data. |
| 404 | The vehicle, trip or other record was not found in your account. |
| 5xx | A temporary server problem. Retry with backoff, and contact 24/7 support if it continues. |
Questions about the API or MCP? Email support@safartrak.com (24/7) or contact the team.