Waypoint Public API

Read-only access to your vehicles' positions, trips and alerts, for your own systems: a fleet-management app, an ERP, a dashboard. Version 1.

Get started

1. In Waypoint, open Manage → API keys and create a key. Copy it straight away: it is shown once and cannot be recovered, only replaced.

2. Call the API with your key. Base address: https://YOUR-WAYPOINT-ADDRESS/public/v1

curl -H "Authorization: Bearer wpk_your_key_here" \
  https://YOUR-WAYPOINT-ADDRESS/public/v1/vehicles
Who can use it. An account needs at least one active licence. A customer account also needs its reseller to have switched API access on. A key only ever sees its own account (a reseller's key sees its customers too), and only vehicles with an active licence.

Machine-readable description: /public/v1/openapi.json (OpenAPI 3).

Authentication

Send the key in the Authorization header as a bearer token. Keys start with wpk_. Never put a key in a web address.

A key can have an expiry date and a list of allowed IP addresses. It stops working when it is revoked, when it expires, or when the account loses its API access.

ScopeAllows
readVehicles, positions, routes, trips. Every key has this.
alertsThe alert feed (SOS, power cut, geofence, overspeed and so on).

There are no write operations in version 1: no commands, no changes.

Vehicles

GET/vehicles

Your licensed vehicles with their latest position. Query: limit (default 200, up to 1000), offset.

{
  "total": 1, "limit": 200, "offset": 0,
  "vehicles": [{
    "id": 7, "name": "Van A", "plate": "GR-1234-24", "make": "Toyota", "model": "Hiace",
    "category": "van", "status": "online", "lastUpdate": "2026-10-26T10:15:02Z", "group": "Deliveries",
    "position": { "latitude": 5.6037, "longitude": -0.187, "speedKmh": 42.0, "courseDegrees": 90,
                  "valid": true, "satellites": 11, "address": "Ring Road, Accra" },
    "ignition": true, "moving": true, "stateSince": "2026-10-26T10:02:11Z", "stateAtLeastSince": null,
    "odometerKm": 48210.4, "totalDistanceKm": 1204.9, "todayDistanceKm": 38.2,
    "fuel": { "value": 61.0, "unit": "%" },
    "batteryVoltage": 12.6, "powerVoltage": 13.1,
    "licence": { "type": "annual", "tier": "core", "expiresAt": "2027-03-01T00:00:00Z" }
  }]
}

status is online, offline or unknown. Fields that a vehicle's tracker does not report are null. stateSince is when moving last changed. When it has not changed for longer than we keep track of (a few days), stateSince is null and stateAtLeastSince says how far back it is known to have lasted. Positions are refreshed every few seconds; asking more often than every 5 seconds returns the same data.

GET/vehicles/{id}

One vehicle, same shape. 404 if it is not yours or not licensed.

GET/me

Your key's name, scopes, expiry, account and rate limit.

Routes and trips

GET/vehicles/{id}/route?from=…&to=…

Position history, oldest first. from and to are ISO 8601 times (UTC), at most 7 days apart. limit defaults to 5000 (up to 20000); if there are more points, truncated is true, so ask for a shorter window.

curl -H "Authorization: Bearer $KEY" \
  "https://YOUR-WAYPOINT-ADDRESS/public/v1/vehicles/7/route?from=2026-10-25T00:00:00Z&to=2026-10-26T00:00:00Z"

{ "vehicleId": 7, "from": "...", "to": "...", "count": 2, "truncated": false,
  "points": [ { "time": "2026-10-25T06:01:10+00:00", "latitude": 5.6, "longitude": -0.18,
                "speedKmh": 0.0, "courseDegrees": 0, "altitude": 61, "valid": true } ] }

GET/vehicles/{id}/trips?from=…&to=…

Trips between two times (up to 92 days): start, end, distance in km, duration in seconds, average and maximum speed, and start and end addresses and coordinates.

Alerts

GET/alerts?since=…&limit=…

Needs the alerts scope. Alerts from since (default: the last 24 hours, at most 7 days back), newest first, for all your licensed vehicles. Types: sos, powerCut, powerRestored, lowBattery, vibration, overspeed, geofenceEnter, geofenceExit, ignitionOn, ignitionOff, offline, online, longIdle, fuelRefill, fuelDrop, maintenanceSoon, maintenanceDue.

{ "since": "2026-10-25T10:00:00+00:00", "count": 1, "alerts": [
  { "id": "e4412", "type": "geofenceExit", "label": "Left geofence", "time": "2026-10-26T08:02:40+00:00",
    "vehicleId": 7, "vehicle": "Van A", "detail": "Depot", "speedKmh": 18.4, "latitude": 5.6, "longitude": -0.18 } ] }

To avoid repeats, remember the newest time you have processed and pass it as since next time; use id to ignore an alert you already have. Push notifications to your own server (webhooks) are planned.

Limits

Each key may make a number of calls per minute that grows with the account's licensed vehicles: 12 per vehicle, at least 60 and at most 3000. Every response carries X-RateLimit-Limit. Over the limit you get 429 and a Retry-After header (seconds). Poll positions no more than every 10 to 30 seconds; for history, ask for the window you need once.

Every call is logged against its key (time, path, result, address) and shown in Waypoint under the key's call log, kept for 30 days.

Errors

Errors are JSON: { "detail": "…" }.

CodeMeaning
400A parameter is wrong (for example a time range that is too long).
401No key, a wrong key, or a key that is revoked, expired or whose issuer is no longer active.
403The key lacks the scope, is used from an address that is not allowed, or the account has no API access (the message says why).
404The vehicle is not yours, is not licensed, or does not exist.
429Too many calls. Wait for Retry-After seconds.

Keeping keys safe

Use a key only from a server you control, never in a web page or mobile app. Give each system its own key so you can revoke one without breaking the others. Add the server's IP address to the key's allowed list. If a key may have leaked, revoke it in Manage → API keys; it stops working immediately.