Skip to content
SearchFree account
Menu
For developers

API and webhooks for garage software

Do you build planning, workshop or dealer software? With a key from the garage your system reads cars, fault codes, reports and trips, and gets a signal when something happens. Read only, and always with the car owner's permission.

The technical reference (endpoints, fields, examples) is in English, like the API itself.

Getting started

  1. The garage has Car-Z Garage. The owner or an admin opens the garage and the Integrations tab.
  2. They create a key with a name and what it may read, and copy it once into your software.
  3. Your software sends the key with every request. For signals, the garage also enters your webhook address there.

Authentication

Send the key in the Authorization header as a Bearer token, over HTTPS only. Never in a URL. One key belongs to one garage; a revoked key stops working at once. We store only a fingerprint of the key, so a lost key cannot be shown again: make a new one.

Authorization: Bearer cz_…

Test the key

curl -s https://car-z.com/api/v1 \
  -H "Authorization: Bearer $CARZ_API_KEY"

List cars (first page of 100)

curl -s "https://car-z.com/api/v1/cars?limit=100" \
  -H "Authorization: Bearer $CARZ_API_KEY"

Fault codes of one car in a period, descriptions in Dutch

curl -s "https://car-z.com/api/v1/cars/$CAR_ID/codes?from=2026-10-01&to=2026-10-31&lang=nl" \
  -H "Authorization: Bearer $CARZ_API_KEY"

Next page

curl -s "https://car-z.com/api/v1/cars/$CAR_ID/trips?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $CARZ_API_KEY"

Endpoints

All endpoints are read-only (GET), versioned in the path and answer JSON with fixed English field names, ISO 8601 dates in UTC and metric units in the field name (distance_km, avg_speed_kmh).

MethodPathScopeWhat
GET/api/v1—The key itself: workspace, scopes, rate limit. Use it to test a key.
GET/api/v1/carscarsCars of the garage, plus customers' cars with running access and download permission. Sorted by id.
GET/api/v1/cars/{car_id}carsOne car.
GET/api/v1/cars/{car_id}/codescodesFault code episodes (first seen until cleared), newest first.
GET/api/v1/cars/{car_id}/reportsreportsInspection reports made in the garage's own workspace (a customer's car: empty list).
GET/api/v1/cars/{car_id}/tripstripsTrip summaries, newest first.

Filters and pages

Lists come in pages. Ask for the next page with the next_cursor of the answer, until it is null. A cursor never skips or repeats a row, even when new rows arrive.

ParameterWhat
limitRows per page, 1–200. Default 50.
cursorThe next_cursor of the previous page. Opaque; pass it back unchanged.
fromYYYY-MM-DD, inclusive (UTC). Codes: seen on or after this day. Trips and reports: started/created on or after.
toYYYY-MM-DD, inclusive (the whole day, UTC). Codes: first seen before the end of this day.
langcodes only: language of the description (en, nl, de, fr, es). Default en.

Answer of a list

{
  "data": [
    {
      "id": "0b9c7d0e-5a3f-4d8e-9c1a-2f6b8e4d7a10",
      "code": "P0420",
      "description": "Catalyst system efficiency below threshold (bank 1)",
      "state": "stored",
      "first_seen_at": "2026-10-02T07:41:12.000Z",
      "last_seen_at": "2026-10-09T16:05:40.000Z",
      "cleared_at": null,
      "days_seen": 4
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wMlQwNzo0MToxMi4wMDBaIiwiaSI6IjBiOWM3ZDBlLi4uIn0"
}

A customer's car: no VIN

{
  "data": {
    "id": "6f1e2d3c-4b5a-4978-8a6b-5c4d3e2f1a0b",
    "access": "shared",
    "name": "Golf",
    "make": "Volkswagen",
    "model": "Golf",
    "year": 2019,
    "plate": "AB-123-C",
    "vin": null,
    "access_expires_at": "2026-12-01T09:00:00.000Z",
    "created_at": "2026-05-04T10:11:12.000Z",
    "updated_at": "2026-11-10T08:00:00.000Z"
  }
}

Errors

An error has an HTTP status and a fixed code: {"error": {"code": "…", "message": "…"}}. Build on the code, not on the message.

StatusCodeWhat
400invalid_parameterA query parameter is not valid (limit, cursor, from, to).
401invalid_keyNo key, an unknown key or a revoked key.
403plan_requiredThe garage has no active paid plan.
403insufficient_scopeThe key does not have the scope of this endpoint.
404not_foundUnknown car, or no access to it. The two are deliberately the same.
429rate_limitedMore than 120 requests in this minute. See Retry-After.
503unavailableTemporarily unavailable. Try again later.

Rate limits

At most 120 requests per minute per key, for all our servers together. Every answer has X-RateLimit-Limit and X-RateLimit-Remaining; above the limit you get 429 with Retry-After in seconds. Fetch changes with a period (from, to) instead of everything every time.

Webhooks

The garage enters one https address and chooses the events, and whether they come one by one or bundled per hour or per day. We send a POST with JSON, signed with the garage's secret.

No alarm fatigue: a garage only hears about a fault that is confirmed, has the check-engine light on and stays, and about each fault only once.

Events

code.confirmedA confirmed code (stored or permanent) with the check-engine light on, not cleared, seen on at least 2 days. Once per episode; again only after clearing and coming back. Pending codes never.
access.grantedA customer's access for your garage started (after accepting and, if asked, the owner's confirmation).
access.endedThat access ended: revoked by the owner or the garage, or expired.
report.createdAn inspection report was made for one of the garage's own cars.
POST https://your-system.example/webhook
Content-Type: application/json
Webhook-Signature: t=1763107200,v1=5f2b…(64 hex)
Webhook-Event: code.confirmed
Webhook-Id: 3a1d…

{
  "id": "3a1d…",
  "type": "code.confirmed",
  "created_at": "2026-11-14T08:00:00.000Z",
  "workspace_id": "…",
  "data": {
    "car_id": "6f1e2d3c-…",
    "code": "P0301",
    "state": "stored",
    "first_seen_at": "2026-11-10T07:02:00.000Z",
    "last_seen_at": "2026-11-13T17:45:00.000Z",
    "days_seen": 3,
    "mil_on": true
  }
}

Digest (hourly or daily): one POST with "type": "digest" and "events": [ … ], each with id, type, created_at, data.

Checking the signature

The header Webhook-Signature has t (Unix time in seconds) and v1 (HMAC-SHA256 of "t.body" with the secret, in hex). Compare in constant time and refuse a t older than 5 minutes, against replay.

// Node.js: check the signature before you trust the body (use the raw body, not re-serialised JSON).
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // replay
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(expected, given);
}
// Answer 2xx quickly. Anything else (or no answer within 10 s) is retried, at most 6 attempts.
// Use the "id" to ignore a delivery you already processed.

Delivery and retries

Answer with a 2xx within 10 seconds. Otherwise we try again later (after 10 minutes, then 30 minutes, 2, 6 and 24 hours), at most 6 times. We never follow a redirect and only send to public addresses. The garage sees the last deliveries in Integrations.

Privacy: the owner decides

  • A customer's car is only visible while the owner has given the garage access, and only if the owner allowed downloading. Revoked or expired means: gone from the API at once.
  • Never the VIN of a customer's car, never locations, never the link of a report.
  • Every request is in the garage's logbook, and for a customer's car also in the owner's. What your system has fetched stays with the garage: treat it as personal data.
  • Read only: the API cannot change anything, clear codes or send anything to a car.

Ready-made link with a specific package?

Links with specific garage packages are on request. Tell us which package you use or build.