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.

VTC Endpoints

REST endpoints under /api/v1/vtcs/* support company management, member rosters, applications, and fleet statistics.

Member Roster

GET /api/v1/vtcs/:vtcId/members

Paginated member roster (page, limit). The optional roleId scopes it to one role and roleMembership selects the direction: has (default) lists the members holding the role, lacks lists the members who do not. roleMembership requires roleId; a role id that belongs to another company is answered as NOT_FOUND, not as an empty roster.

Member Departure

POST /api/v1/vtcs/:vtcId/leave

Allows an active non-owner member to leave the company workspace. Company owners cannot leave without first transferring ownership or deleting the company. Role assignments and membership records are removed, and the company member count is updated.

Withdraw Application

POST /api/v1/vtcs/:vtcId/applications/:applicationId/withdraw

Allows an applicant to withdraw their pending application before company dispatchers review it. Note that when an applicant is accepted into any VTC or creates a new VTC, competing pending applications across other VTCs are automatically withdrawn.

REST API