{ "openapi": "3.1.0", "info": { "title": "Battery Health Check Marketplace API", "version": "1.0.0", "summary": "Look up an AVILOO battery test by VIN or registration and retrieve its certificate.", "description": "REST + outbound webhooks for marketplaces and listing platforms.\n\n`GET /tests` requires `vin` or `registration` on a marketplace credential: it answers \"what do you know about this car\", across every Battery Health Check dealer. It is not a listing endpoint, and `dealer_id` or `since`/`until` alone will not open one — those narrow a lookup, they do not replace it. That restriction is what makes the reach reasonable.\n\nFull guide, worked examples and webhook signing: https://marketplaces.batteryhealthcheck.co.uk\n\nWe do not currently provide a public sandbox. For development, a representative sample response pack is published at https://marketplaces.batteryhealthcheck.co.uk/sample_responses.json, covering successful, provisional and other result states. When an integration is ready for validation, we recommend a pilot using real tests with a participating dealer.\n\n**Conventions.** HTTPS/TLS 1.2+. All timestamps ISO 8601 UTC. Page-based pagination, `per_page` capped at 100. We never drop a key: anything we do not hold serialises as `null`, so the shape is stable — but you must null-check before rendering. New fields may be added without notice; ignore keys you do not recognise. Breaking changes ship on a new version path, never in place.\n\nRate limits are applied per credential and per endpoint group. A ceiling of 300 requests per minute also applies per source IP address across all endpoints, which is the relevant limit for a platform calling on behalf of many dealers from a small number of hosts.", "contact": { "name": "Battery Health Check", "email": "info@batteryhealthcheck.co.uk", "url": "https://marketplaces.batteryhealthcheck.co.uk" } }, "servers": [ { "url": "https://api.batteryhealthcheck.co.uk/v1", "description": "Production — the only environment." } ], "security": [ { "clientCredentials": [] } ], "tags": [ { "name": "Tests", "description": "Battery test results and certificates." }, { "name": "Webhooks", "description": "Outbound event delivery." } ], "paths": { "/oauth/token": { "post": { "operationId": "issueToken", "summary": "Exchange credentials for a token", "description": "OAuth 2.0 client-credentials grant, form-encoded. Returns a JWT valid for one hour. **Cache it** — this endpoint is limited to 10 requests a minute.\n\nNote the response is wrapped in the standard `{\"data\": …}` envelope rather than the bare OAuth body.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string", "description": "Optional space-separated subset of your granted scopes. Omit for all of them." } } } } } }, "responses": { "200": { "description": "A bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Token" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "400": { "description": "`invalid_request`, `invalid_grant_type` or `invalid_scope`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_client` — credentials not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`credential_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`too_many_requests` — cache your token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tests": { "get": { "operationId": "listTests", "summary": "Find tests", "description": "Search by VIN or by registration. **Join on `vin`** — plates transfer between vehicles and a test recorded without a plate can only be found by VIN.\n\nMarketplace credentials must supply `vin` or `registration`: on those, a request with neither returns `400 invalid_request`, and `dealer_id` or `since`/`until` alone is not a substitute. Dealer-group credentials may list without a filter.", "security": [ { "clientCredentials": [ "read:tests" ] } ], "responses": { "200": { "description": "A page of tests, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Test" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." }, "page": { "type": "integer" }, "per_page": { "type": "integer", "description": "Capped at 100." }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Read this, not the length of `data`." } } } } } } } }, "400": { "description": "`invalid_field` on `vin`, `registration`, `page` or `per_page`; `invalid_request` when a marketplace credential supplies neither `vin` nor `registration`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "vin", "in": "query", "description": "Full 17-character VIN for an exact match, or 3+ characters for a prefix match.", "schema": { "type": "string", "minLength": 3, "maxLength": 17 } }, { "name": "registration", "in": "query", "description": "Number plate. Exact match, case and space insensitive.", "schema": { "type": "string" } }, { "name": "dealer_id", "in": "query", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "description": "ISO 8601. Tests from this instant onwards.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "ISO 8601. Tests up to this instant.", "schema": { "type": "string", "format": "date-time" } } ] } }, "/tests/{test_id}": { "get": { "operationId": "getTest", "summary": "Get a test", "description": "Interpret `battery.soh_percent` together with `result_status` before displaying it publicly. `vehicle_supported` describes the model and is a separate consideration.", "security": [ { "clientCredentials": [ "read:tests" ] } ], "responses": { "200": { "description": "The test, including diagnostics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Test" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "test_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/tests/{test_id}/certificate": { "get": { "operationId": "getCertificate", "summary": "Get the full certificate (PDF)", "description": "The complete certificate, including the VIN. Intended for the dealer record rather than public display; use the preview endpoint for public-facing use.", "security": [ { "clientCredentials": [ "read:certificates" ] } ], "responses": { "200": { "description": "A short-lived signed URL to the PDF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignedUrl" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "409": { "description": "`certificate_not_ready` — not rendered yet. The body carries `retry_after_seconds`; requesting it starts rendering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`service_unavailable` — signing temporarily unavailable, retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "test_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/tests/{test_id}/preview": { "get": { "operationId": "getPreview", "summary": "Get the publishable preview (JPEG)", "description": "Public-facing certificate image. The VIN is not shown and the certificate number is masked. Includes a QR code linking to AVILOO's hosted validation page.", "security": [ { "clientCredentials": [ "read:certificates" ] } ], "responses": { "200": { "description": "A short-lived signed URL to the JPEG.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignedUrl" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "409": { "description": "`preview_not_ready` — not rendered yet. The body carries `retry_after_seconds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`service_unavailable` — signing temporarily unavailable, retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "test_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List your webhook endpoints", "description": "", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "Your endpoints. Secrets are not returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint", "description": "", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "The created endpoint. **This is the only time `secret` is returned.**", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "422": { "description": "`invalid_webhook_url` or `webhook_limit_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS only. Must be publicly resolvable and must not point at a private range." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "bhc.dealer.activated", "bhc.test.completed", "bhc.test.failed" ] } } } } } } } } }, "/webhooks/{webhook_id}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook endpoint", "description": "", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "The endpoint, including delivery health.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "description": "", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "The deleted endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/webhooks/{webhook_id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test ping", "description": "Delivers a `bhc.webhook.test` event. Test events are notifications rather than complete result payloads and carry no vehicle or battery fields. Consumers should branch on the event type before reading `data`.", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "Ping queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/webhooks/{webhook_id}/replay": { "post": { "operationId": "replayWebhook", "summary": "Replay deliveries", "description": "Re-sends past deliveries to this endpoint. Limited to 5 requests a minute.", "security": [ { "clientCredentials": [ "manage:webhooks" ] } ], "responses": { "200": { "description": "Replay queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Echoes the `X-Request-Id` response header. Include it when contacting support." } } } } } } } }, "404": { "description": "`not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "`invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired token — `missing_authorization`, `invalid_token`, `invalid_audience`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the scope, is revoked, or the source address is not allowed — `insufficient_scope`, `credential_disabled`, `credential_not_found`, `ip_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — `too_many_requests`. No `Retry-After` header is sent; limits are per-minute windows, so back off at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time", "description": "ISO 8601. Replay deliveries from this instant." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Restrict the replay to these event types." } } } } } } } } }, "components": { "securitySchemes": { "clientCredentials": { "type": "oauth2", "description": "Exchange `client_id` + `client_secret` for a one-hour JWT, then send it as `Authorization: Bearer `. Marketplace credentials are issued by Battery Health Check by agreement; there is no self-serve route.", "flows": { "clientCredentials": { "tokenUrl": "https://api.batteryhealthcheck.co.uk/v1/oauth/token", "scopes": { "read:tests": "List and look up battery tests (including VIN lookup)", "read:certificates": "Download certificate PDFs and preview images", "manage:webhooks": "Register, list, delete and replay webhooks" } } } } }, "schemas": { "Test": { "type": "object", "properties": { "id": { "type": "integer", "description": "BHC identifier for the test." }, "internal_reference": { "type": [ "string", "null" ], "description": "Partner-defined identifier. Stored against the test and returned unchanged, so a partner can correlate BHC records with records in its own platform. Maximum 100 characters. Not validated for uniqueness, and not currently editable once set." }, "dealer_id": { "type": [ "integer", "null" ], "description": "The dealer the test belongs to." }, "unit_id": { "type": [ "integer", "null" ], "description": "The AVILOO unit that performed the test." }, "status": { "type": [ "string", "null" ], "description": "Lifecycle state of the test record.", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled", null ] }, "vehicle": { "type": [ "object", "null" ], "description": "The vehicle tested.", "properties": { "registration": { "type": [ "string", "null" ], "description": "Vehicle registration as recorded against the test. Not present on every test. Registrations can be transferred between vehicles, so match on `vin` where one is available." }, "vin": { "type": [ "string", "null" ], "description": "Vehicle Identification Number, 17 characters. The stable identifier for matching a result to a vehicle record." }, "make": { "type": [ "string", "null" ], "description": "Manufacturer as reported by AVILOO." }, "model": { "type": [ "string", "null" ], "description": "Model as reported by AVILOO. The value often includes the pack size, for example `MG4 Electric - 77,0 kWh`, and uses a decimal comma. Treat it as a display string rather than a normalised model code." }, "year": { "type": [ "integer", "null" ], "description": "Model year." }, "mileage_km": { "type": [ "number", "null" ], "description": "Odometer reading at the time of test. Unit: kilometres." } } }, "battery": { "type": [ "object", "null" ], "description": "Headline battery figures.", "properties": { "soh_percent": { "type": [ "number", "null" ], "description": "State of Health measured by AVILOO. Interpret together with `result_status` before displaying this value. Values above 100 occur on models still in AVILOO validation. Unit: percent." }, "capacity_kwh": { "type": [ "number", "null" ], "description": "Measured usable capacity. Unit: kWh." }, "nominal_kwh": { "type": [ "number", "null" ], "description": "Nominal capacity when new. Unit: kWh." }, "estimated_range_miles": { "type": [ "number", "null" ], "description": "Estimated range at the measured capacity. Null where AVILOO did not derive one. Unit: miles." }, "cell_count": { "type": [ "integer", "null" ], "description": "Number of cells in the pack." }, "cell_variance": { "type": [ "number", "null" ], "description": "Spread across cell voltages. Lower values indicate a more balanced pack. Unit: volts." } } }, "tested_at": { "type": [ "string", "null" ], "description": "When the test was performed.", "format": "date-time" }, "results_received_at": { "type": [ "string", "null" ], "description": "When BHC received the result from AVILOO.", "format": "date-time" }, "diagnostics": { "type": [ "object", "null" ], "description": "AVILOO's extended detail record, normalised. Null on tests recorded before detail capture, and on tests that have not completed.", "properties": { "overall_battery_status": { "type": [ "string", "null" ], "description": "AVILOO's overall assessment of the pack.", "enum": [ "OK", "WARNING", "NOT_CONCLUSIVE", "SAFETY_ISSUE", null ] }, "battery_checks": { "type": [ "object", "null" ], "description": "Per-check results: `battery_management_system`, `battery_sensors`, `battery_pack_parameters`, `battery_cell_voltages`, `vehicle_communication`. Each value is a status string." }, "sensor_checks": { "type": [ "object", "null" ], "description": "Per-sensor results: `voltage_sensor`, `current_sensor`, `temperature_sensors`, `cell_voltage_sensors`. Each value is a status string." }, "energy_kwh": { "type": [ "object", "null" ], "description": "Gross, net and usable energy, each given when new and at the measured state. Unit: kWh." }, "range": { "type": [ "object", "null" ], "description": "Typical and personal range in miles; WLTP figures in kilometres as `{from, to}` objects. Units differ between the two — see the units table." }, "measurements": { "type": [ "object", "null" ], "description": "Cell temperature (°C) and cell voltage (V) as `{min, max, delta, status}`; pack voltage (V), average current (A) and mileage (km) as scalars." }, "bms": { "type": [ "object", "null" ], "description": "Values reported by the vehicle's own battery management system, and AVILOO's assessment of how accurate each is. These are the vehicle's self-reported figures. `battery.soh_percent` is AVILOO's independent measurement; the two are separate fields and may differ." }, "vehicle_supported": { "type": [ "boolean", "null" ], "description": "Model-level support flag as recorded in the detail record. Mirrored at the top level of the test object." } } }, "warnings": { "type": [ "array", "null" ], "description": "AVILOO warning codes raised on this test, for example `SOH_GREATER_THAN_100` or `UNCLEAR_MODEL`. An empty array means no warnings were raised. Null means no AVILOO payload is stored for this test, which is not the same statement.", "items": { "type": "string" } }, "vehicle_supported": { "type": [ "boolean", "null" ], "description": "False while the vehicle model is still in AVILOO validation. Describes the model, not this result — see `result_status` for the result." }, "result_status": { "type": [ "string", "null" ], "description": "How the measured State of Health should be treated. `final`: a complete result. `provisional`: a value was produced but AVILOO reference data for the model is not final, and the value may exceed 100. `inconclusive`: AVILOO completed the test without reaching a result, and no value will follow. Null: the result is not yet available, or the record predates this field. Describes this result; `vehicle_supported` describes the model.", "enum": [ "final", "provisional", "inconclusive", null ] }, "certificate_number": { "type": [ "string", "null" ], "description": "AVILOO certificate number." }, "certificate_available": { "type": "boolean", "description": "Whether the full certificate PDF can be retrieved." }, "preview_available": { "type": "boolean", "description": "Whether the public-facing certificate image can be retrieved." }, "created_at": { "type": [ "string", "null" ], "description": "When the record was created.", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "description": "When the record was last updated.", "format": "date-time" } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer", "description": "BHC identifier for the endpoint." }, "url": { "type": "string", "description": "Destination URL. HTTPS only.", "format": "uri" }, "events": { "type": [ "array", "null" ], "description": "Event types delivered to this endpoint.", "items": { "type": "string", "enum": [ "bhc.dealer.activated", "bhc.test.completed", "bhc.test.failed" ] } }, "disabled_at": { "type": [ "string", "null" ], "description": "Set when the endpoint was disabled after repeated delivery failures.", "format": "date-time" }, "consecutive_failures": { "type": "integer", "description": "Consecutive failed deliveries. Resets on a successful delivery." }, "last_success_at": { "type": [ "string", "null" ], "description": "Last successful delivery.", "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "description": "Last delivery attempt.", "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "description": "When the endpoint was registered.", "format": "date-time" }, "secret": { "type": [ "string", "null" ], "description": "Signing secret. Returned once, when the endpoint is created, and not retrievable afterwards." } } }, "Token": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds. 3600." }, "scope": { "type": "string", "description": "Space-separated scopes actually granted." } } }, "SignedUrl": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Short-lived signed URL. Fetch it promptly; do not store it." }, "expires_at": { "type": "string", "format": "date-time", "description": "One hour out." }, "content_type": { "type": "string" }, "certificate_number": { "type": [ "string", "null" ], "description": "Certificate endpoint only." } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string" }, "request_id": { "type": "string" }, "field": { "type": "string", "description": "Present on `invalid_field` — names the offending field." }, "retry_after_seconds": { "type": "integer", "description": "Present on `certificate_not_ready` / `preview_not_ready`." } } } } } } } }