waylog docs

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

Routing Schema

Endpoints are mounted in apps/server/src/routes/ and grouped by domain:

/api/v1/*: REST endpoints — public, session, native bearer (wl_...), or VTC API key (wlk_...) authentication depending on the route. Global 200 req/min.
/api/auth/*: Better Auth endpoints (20 req/min).
/trpc: tRPC for first-party TypeScript clients.
/webhooks/*: Unauthenticated endpoints secured via HMAC signature validation (500 req/min).

Authentication

Three actor types are supported via the Authorization header / session cookie:

Actor	Credential	Used by
Browser session	Better Auth cookie	Web frontend (SSR)
Native client	`Bearer wl_...` token (SHA-256 hashed in `nativeSession`)	Tauri desktop client
Third party	`Bearer wlk_...` VTC API key (SHA-256 hashed in `vtc_api_key`)	VTC dispatch tools, bots, integrations

VTC API keys are scoped (jobs:*, members:*, applications:*, stats:read), minted and revoked via POST|GET /api/v1/vtcs/:vtcId/api-keys (+ /revoke), and can only access the VTC they were created for. The plaintext key is shown exactly once at mint time.

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 performs an optimized UPSERT operation on the jobLiveState table to power real-time web dashboards.

In-Game Events

POST /api/v1/jobs/:id/events

Accepts progressive in-game events while driving (fines, tollgates, refuels, ferry rides, collisions, etc.) and maintains live event totals on the job record.

Route Chunks

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

Accepts sealed, immutable chunks of RDP-compressed 9-field coordinate tuples ([posX, posY, posZ, heading, speedKmh, fuelAmount, cargoDamage, gameTime, capturedAt]) uploaded when a job completes for route reconstruction and replay.

REST API