REST API

The Waylog Fastify server exposes traditional REST endpoints for high-frequency data ingestion, public data access, and third-party integrations.

Routing Schema

Endpoints are logically separated into file-based domains using @fastify/autoload.

• /api/v1/public/*: Open endpoints. Subject to standard rate limiting (60 req/min). Used for public profiles and caching TruckersMP data.
• /api/v1/private/*: Guarded endpoints. Requires an active session. Subject to higher rate limits (120 req/min).
• /webhooks/*: Unauthenticated endpoints secured via HMAC signature validation.

Standard Envelope

Every REST response is strictly enveloped to ensure predictable client-side error handling.

Success Response

{
  "ok": true,
  "data": {
    "id": "123",
    "status": "in_progress"
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid payload provided",
    "details": [
      { "field": "speed", "issue": "Must be a positive number" }
    ]
  }
}

High-Frequency Endpoints

Certain routes are heavily optimized for the desktop client's telemetry polling.

Live Telemetry State

PUT /api/v1/jobs/live

Accepts a JSONB payload representing the absolute current state of the truck. This endpoint has an elevated rate limit (300 req/min) and performs an optimized UPSERT operation on the jobLiveState table to power real-time web dashboards.

Route Breadcrumbs

POST /api/v1/jobs/:id/route-points

To minimize network overhead, GPS coordinates are not sent individually. The desktop client batches them and sends arrays of route points to this endpoint, which performs a bulk database insertion.