Fleet management API for Vethy VS02 PRO: REST + GraphQL for custom integrations

• Table of Contents

1. REST API: endpoints for telemetry, config, OTA, diagnostics
2. GraphQL API: efficient queries for dashboards
3. OAuth 2.0 authentication and role-based access control
4. Webhook events: real-time push for fault alerts and OTA completion

Many large fleet operators with 500+ trucks build proprietary fleet management platforms in-house rather than relying solely on Geotab, Samsara or Webfleet. For these fleets, Vethy provides direct REST and GraphQL API access to all Vethy VS02 PRO and V-FMSG-24 telemetry, configuration, OTA management, and BMS diagnostics. This page documents the API endpoints, OAuth 2.0 authentication flow, webhook event subscriptions, rate limits and common integration patterns used by fleet IT teams at Schneider National, J.B. Hunt, Mærsk, DSV, DB Schenker and Kuehne+Nagel.

REST API: endpoints for telemetry, config, OTA, diagnostics

Base URL: https://api.vethy.com/v2/. Primary endpoints: **GET /fleet/{fleet_id}/vehicles** — list all vehicles with VS02 PRO. **GET /vehicles/{vin}/telemetry?from=&to=&fields=** — historical telemetry (runtime, SoC, temp, energy). **GET /vehicles/{vin}/telemetry/live** — current state. **GET /vehicles/{vin}/diagnostics** — BMS fault codes and health. **POST /vehicles/{vin}/config** — push set-point, AC enable/disable, OTA schedule. **GET /vehicles/{vin}/ota/status** — firmware version and update history. All responses JSON with pagination, ISO 8601 timestamps, and rate-limit headers (X-RateLimit-Remaining).

GraphQL API: efficient queries for dashboards

GraphQL endpoint: https://api.vethy.com/graphql. Single query can fetch fleet-wide AC summary, per-vehicle live state, recent BMS faults, and OTA pending updates in one round-trip. Sample query: query FleetDashboard { fleet(id: "abc") { vehicleCount, totalAcRuntimeHours, avgLithiumSoc, vehicles(filter: { faultCount_gt: 0 }) { vin, driverName, lithiumSoc, faults { code, severity, since } } } }. GraphQL subscriptions support real-time updates over WebSocket — used by Schneider National for live operations dashboards.

OAuth 2.0 authentication and role-based access control

Vethy API uses OAuth 2.0 Authorization Code flow for user-context access and Client Credentials flow for server-to-server. Roles: fleet-viewer (read telemetry), fleet-operator (read + config writes), fleet-admin (read + config + OTA management), security-auditor (read audit logs only). Tokens expire 1 hour with refresh-token rotation. All API calls logged for SOC 2 Type II audit compliance. Vethy publishes OpenAPI 3.1 spec and Postman collection.

Webhook events: real-time push for fault alerts and OTA completion

Configure webhook URL via POST /fleet/{fleet_id}/webhooks. Events: ac.fault.critical, ac.fault.warning, ac.fault.resolved, ota.update.scheduled, ota.update.installing, ota.update.success, ota.update.failed, lithium.soc.low, lithium.capacity.degraded. Payload signed with HMAC-SHA256 using shared secret. Webhook retries with exponential backoff (5 attempts over 24 hours). Used by Mærsk for real-time integration into central NOC (network operations center).

Frequently asked questions

Is API access included with VS02 PRO or extra cost?

API access is included in the Vethy Fleet+ subscription (€8/truck/month). Standalone VS02 PRO purchases without Fleet+ have limited API access (last 30 days telemetry, no webhook subscriptions). Geotab/Samsara/Webfleet integration via FMS gateway has no additional Vethy API cost.

What rate limits apply to the API?

Default: 100 requests/min per OAuth client, 10,000 requests/day. Fleet+ subscribers can request rate limit increases up to 1,000/min, 1,000,000/day. GraphQL queries with complexity > 1000 are throttled separately. Webhook delivery is unlimited but capped at 100 events/second per webhook URL.

Does Vethy publish SDKs in Python, Node.js, Java or .NET?

Yes — official SDKs at github.com/vethy/vethy-sdk in Python (vethy-sdk-python), Node.js (vethy-sdk-js), Java (vethy-sdk-java) and .NET (Vethy.SDK). Community SDKs available for Go, Ruby and Rust. All SDKs handle OAuth refresh, rate-limit back-off, and webhook signature verification automatically.

How is API uptime guaranteed?

Vethy API SLA: 99.95% monthly uptime for Fleet+ subscribers, 99.9% for standalone. Multi-region deployment across AWS eu-west-1 (Ireland), us-east-1 (Virginia), ap-southeast-1 (Singapore). Status page at status.vethy.com with historical uptime and incident post-mortems.