Get API Access
Velocity Platform · v2

Vehicle data your application can explain.

Velocity unifies connected-car, OBD, and manual evidence without hiding its origin, freshness, or uncertainty.

Get API KeyJump to API

Start here

Quickstart

  1. Create an organization and sandbox application in the console.
  2. Create a scoped API key and store it only on your backend.
  3. Connect a Smartcar live or simulated vehicle, use optional DIMO, or ingest a manual/OBD event.
  4. Read available observations and assessments; absent projections remain explicitly unknown.
Example
curl "https://velocity-api-production-4e2f.up.railway.app/v2/vehicles" \
  -H "x-api-key: vel_sandbox_app12345.your_secret"

Truth and lineage

Canonical data model

Raw events

Immutable provider payloads with checksums, source IDs, consent scope, and receive time.

Observations

VSS-style signals with source and normalized units, quality, and observed time.

Assessments

Versioned health and financial projections with evidence, confidence, and freshness.

Unknown data is not healthy data. A diagnostic trouble code is evidence, not a confirmed diagnosis.

Contract first

REST API

Production base URL: https://velocity-api-production-4e2f.up.railway.app. Operational probes are available at /healthz and /readyz.

GET/v2/vehicles

List canonical tenant-owned vehicles.

GET/v2/vehicles/:id

Read one canonical tenant-owned vehicle.

POST/v2/ingestion/events

Replay-safe source-envelope ingestion. Requires Idempotency-Key.

POST/v2/provider-authorizations

Begin user-authorized Smartcar Connect. Requires a bearer session and Idempotency-Key.

GET/v2/provider-connections

List provider connections scoped to the calling application.

GET/v2/vehicles/:id/observations

Read canonical observations with quality and source provenance.

GET/v2/vehicles/:id/profile

Read evidence-qualified mechanical, financial, and maintenance sections.

POST/v2/webhooks

Create an application-owned endpoint and reveal its signing secret once.

POST/v2/management/provisioning-runs

Admin-only Ora or MechanicOS provisioning with fixed partner scopes and explicit vehicle grants.

GET/v2/credentials/self

Inspect the calling partner credential, scopes, and granted vehicle IDs.

Compatibility transition

Move from v1 to v2

New integrations must use the contract-owned /v2 routes and velocity.v2 SDK resources. Existing v1 routes now return a Deprecation: true header and a stable operation ID so real usage can be measured before any removal. No sunset date is asserted yet.

Typed client

TypeScript SDK

The SDK provides scoped authentication, timeouts, cursor pagination, idempotency, safe GET retries, and standard errors.

Example
import { VelocityClient } from "@velocity/sdk";

const velocity = new VelocityClient({
  baseUrl: process.env.VELOCITY_API_URL!,
  apiKey: process.env.VELOCITY_API_KEY!,
});

const page = await velocity.v2.vehicles.list();
const vehicle = await velocity.v2.vehicles.get(page.data[0].id);
const profile = await velocity.v2.profiles.get(vehicle.id);
const observations = await velocity.v2.observations.list(vehicle.id);

Event delivery

Signed webhooks

Triggers can deliver assessment updates to application-owned endpoints. Velocity signs the exact payload and timestamp. Deliveries use bounded exponential backoff and stable IDs.

Example
const signature = request.headers["velocity-signature"];
// Verify timestamp + HMAC before reading the event.
// Reject old timestamps and previously processed delivery IDs.

Agent access

MCP server

Configure VELOCITY_API_URL and a read-scoped VELOCITY_API_KEY, then run velocity-mcp. The server exposes vehicle, timeline, health, financial, and maintenance reads. It intentionally exposes no destructive tools. Canonical projection, decision, and evidence-backed recommendation tools preserve freshness and never present a DTC as a confirmed diagnosis.

Connected vehicles

Smartcar primary integration

Smartcar Connect supports live OEM accounts and simulated vehicles. Velocity uses API v3 application authentication, exact signed webhooks, and Dashboard-managed least-privilege signals without location. DIMO remains optional and OBD remains the fallback.

User control

Consent and privacy

  • Request only signals required by the application.
  • Display provider, scope, grant time, expiry, and sync status.
  • Support immediate provider revocation. Export and verified deletion remain unavailable until their durable privacy workers ship.
  • Keep precise location out of logs and generic assessment payloads.

Independent sibling products

Ora and MechanicOS provisioning

Use the console Partners page or management API to create a partner application. Velocity assigns the immutable contract-owned profile, then an admin grants specific vehicles and issues a one-time credential. The application can activate only after an active credential, a live vehicle grant, and a verified HTTPS webhook are present.

  • Never persist the returned credential or webhook secret in a client.
  • Rotate credentials with a bounded overlap before revoking the old generation.
  • Verify webhook ownership before production activation.
  • Ora and MechanicOS remain separate repositories and databases; they consume only versioned Velocity contracts.