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
- The garage has Car-Z Garage. The owner or an admin opens the garage and the Integrations tab.
- They create a key with a name and what it may read, and copy it once into your software.
- 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.app/api/v1 \
-H "Authorization: Bearer $CARZ_API_KEY"List cars (first page of 100)
curl -s "https://car-z.app/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.app/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.app/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).
| Method | Path | Scope | What |
|---|---|---|---|
| GET | /api/v1 | — | The key itself: workspace, scopes, rate limit. Use it to test a key. |
| GET | /api/v1/cars | cars | Cars of the garage, plus customers' cars with running access and download permission. Sorted by id. |
| GET | /api/v1/cars/{car_id} | cars | One car. |
| GET | /api/v1/cars/{car_id}/codes | codes | Fault code episodes (first seen until cleared), newest first. |
| GET | /api/v1/cars/{car_id}/reports | reports | Inspection reports made in the garage's own workspace (a customer's car: empty list). |
| GET | /api/v1/cars/{car_id}/trips | trips | Trip 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.
| Parameter | What |
|---|---|
| limit | Rows per page, 1–200. Default 50. |
| cursor | The next_cursor of the previous page. Opaque; pass it back unchanged. |
| from | YYYY-MM-DD, inclusive (UTC). Codes: seen on or after this day. Trips and reports: started/created on or after. |
| to | YYYY-MM-DD, inclusive (the whole day, UTC). Codes: first seen before the end of this day. |
| lang | codes 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.
| Status | Code | What |
|---|---|---|
| 400 | invalid_parameter | A query parameter is not valid (limit, cursor, from, to). |
| 401 | invalid_key | No key, an unknown key or a revoked key. |
| 403 | plan_required | The garage has no active paid plan. |
| 403 | insufficient_scope | The key does not have the scope of this endpoint. |
| 404 | not_found | Unknown car, or no access to it. The two are deliberately the same. |
| 429 | rate_limited | More than 120 requests in this minute. See Retry-After. |
| 503 | unavailable | Temporarily 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.confirmed | A 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.granted | A customer's access for your garage started (after accepting and, if asked, the owner's confirmation). |
| access.ended | That access ended: revoked by the owner or the garage, or expired. |
| report.created | An 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.