Vehicle data your application can explain.

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.

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

Contract first

REST API

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

Vehicle intelligence API

Orá-1 Velocity

Orá-1 Velocity is Velocity's evidence-grounded vehicle copilot interface. Your product owns the chat UI and transcript; Velocity evaluates the latest tenant-scoped vehicle evidence and returns a validated answer with citations, freshness, confidence, and safe suggested actions. The calling credential needs the recommendations:read scope.

curl -X POST "https://velocity-api-production-4e2f.up.railway.app/v2/vehicles/veh_01HQ/ora/chat/completions" \
  -H "x-api-key: $VELOCITY_API_KEY" \
  -H "content-type: application/json" \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "What should I review for this vehicle today?"
      }
    ]
  }'

• Send at most 13 user or assistant messages, up to 16,000 characters total. The final message must be from the user.
• The chat endpoint is stateless: retain the transcript in your application and append data.message to the next request.
• An answer requires a completed canonical assessment and fresh relevant evidence. Velocity returns 409 agent_insufficient_data when that requirement is not met.
• Model tokens are not streamed before validation. Render the fully validated data.message and its data.evidence together.

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.

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.

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.