{ "openapi": "3.1.0", "info": { "title": "POXA Scrap Car Quote API", "version": "2026-11-03", "description": "Instant self-service keys in Breaker Value → Scrap Car Quote API. Same request contract in the playground and server integrations. Each live valuation uses one credit from your account, the same credits as Breaker Value on the website and Auctions; a failed valuation gives its credit back. Accepted attempts count towards the daily cap even on failure, except calls refused for credits. Test mode returns a synthetic fixture and is free. Accounts on older plans use their monthly Breaker Value searches instead." }, "servers": [ { "url": "https://poxa.co.uk/api/v1", "description": "Production" }, { "url": "https://dev.poxa.co.uk/api/v1", "description": "Development; use keys created on dev" } ], "security": [ { "bearerKey": [] } ], "paths": { "/breaker-value": { "post": { "operationId": "createBreakerValue", "summary": "Value a vehicle", "description": "Send exactly one VIN or registration. Optional damage areas and photos are combined. Allow up to 120 seconds. A required Idempotency-Key prevents duplicate charges: identical retries replay the saved response for 30 days; conflicting payloads return 409. Replays are scoped to the key owner, account, mode and environment, so rotating a key keeps access to that owner’s saved valuations. After a stored failure, use a NEW key to intentionally retry.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "examples": { "vehicle": { "value": { "vin": "WVWZZZAUZFW321566", "damage": [ { "area": "front_end", "side": "nearside" } ], "min_part_value": 40, "vat": "inc", "detail": "full", "reference": "your-stock-reference" } } } } } }, "responses": { "200": { "description": "Complete valuation. Live: one credit (older plans: one monthly Breaker Value search); sandbox: free.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "POXA-Version": { "schema": { "type": "string" }, "description": "Response contract version." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Account daily cap for this mode. Present on accepted authenticated requests." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Lower of key and account remaining daily requests." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Next UTC midnight, Unix seconds." }, "POXA-Credits-Remaining": { "schema": { "type": "integer" }, "description": "Credits left this period for the whole account, after this call." }, "POXA-Credits-Limit": { "schema": { "type": "integer" }, "description": "Credits this period: the plan’s plus any bought." }, "POXA-Credits-Reset": { "schema": { "type": "integer" }, "description": "When the credits reset, Unix seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" }, "examples": { "sandbox": { "summary": "Synthetic sandbox fixture; runtime-generated.", "value": { "id": "bv_example", "object": "breaker_value", "api_version": "2026-11-03", "mode": "test", "created_at": "2026-10-20T12:00:00.000Z", "expires_at": "2026-11-19T12:00:00.000Z", "reference": "your-stock-reference", "vehicle": { "vin": "WVWZZZAUZFW321566", "reg": "DEMO1", "make": "Demo", "model": "Hatchback", "variant": null, "year": 2015, "title": "Sandbox demonstration vehicle" }, "value": { "currency": "GBP", "vat": "inc", "parts": 4, "low": 952, "average": 1640.5, "horizons": [ { "months": 1, "within_days": 30, "parts": 0, "low": 0, "average": 0 }, { "months": 3, "within_days": 90, "parts": 1, "low": 630, "average": 1020 }, { "months": 6, "within_days": 180, "parts": 2, "low": 840, "average": 1402.5 }, { "months": 9, "within_days": 270, "parts": 4, "low": 952, "average": 1640.5 }, { "months": 12, "within_days": 365, "parts": 4, "low": 952, "average": 1640.5 } ] }, "demand": { "score": 8, "tier": "hot", "model_version": "sold-db-2026-10-08-v1-demand-v7" }, "damage": { "areas": [ { "area": "front_end", "side": "nearside" } ], "images_received": 0, "images_status": "not_requested", "excluded": { "parts": 1, "low": 56, "average": 102 } }, "inventory": { "status": "not_checked_in_test_mode", "systems": [], "as_of": null, "overlap": null }, "parts": [ { "id": "part_1", "name": "Engine", "area": "powertrain", "side": null, "quantity": 1, "oem_numbers": [ "DEMO1" ], "low": 630, "average": 1020, "sold_12m": 40, "active_listings": 2, "demand": { "score": 10, "tier": "hot", "sells_in_days": 38 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_2", "name": "Gearbox", "area": "powertrain", "side": null, "quantity": 1, "oem_numbers": [ "DEMO2" ], "low": 210, "average": 382.5, "sold_12m": 8, "active_listings": 1, "demand": { "score": 6, "tier": "mid", "sells_in_days": 121 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_4", "name": "Door (Right)", "area": "doors", "side": "offside", "quantity": 1, "oem_numbers": [ "DEMO4" ], "low": 42, "average": 85, "sold_12m": 1, "active_listings": 0, "demand": { "score": 5, "tier": "mid", "sells_in_days": 202 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_5", "name": "Tailgate", "area": "rear", "side": null, "quantity": 1, "oem_numbers": [ "DEMO5" ], "low": 70, "average": 153, "sold_12m": 1, "active_listings": 1, "demand": { "score": 4, "tier": "mid", "sells_in_days": 243 }, "photo_assessment": null, "excluded_reason": null } ], "removed": [ { "id": "part_3", "name": "Headlight (Left)", "area": "front_end", "side": "nearside", "quantity": 1, "oem_numbers": [ "DEMO3" ], "low": 56, "average": 102, "sold_12m": 2, "active_listings": 0, "demand": { "score": 5, "tier": "mid", "sells_in_days": 180 }, "photo_assessment": null, "excluded_reason": "damage_area" }, { "id": "part_6", "name": "Dashboard", "area": "interior", "side": null, "quantity": 1, "oem_numbers": [ "DEMO6" ], "low": 28, "average": 59.5, "sold_12m": 1, "active_listings": 3, "demand": { "score": 3, "tier": "low", "sells_in_days": 333 }, "photo_assessment": null, "excluded_reason": "below_min_part_value" } ], "data": { "priced_at": "2026-10-20T00:00:00Z", "market_stock_as_of": "2026-10-20", "pricing_updated_at": "2026-10-20T00:00:00Z" }, "warnings": [ "Sandbox fixture. These are illustrative values, not a valuation of the supplied vehicle.", "Revenue estimates assume parts are listed now at competitive prices. They are not a sale guarantee or profit forecast.", "Low and average are conservative per-part estimates matching the Breaker Value app; the adjustments are already included. VAT ex applies a 20% adjustment, not a margin-scheme calculation." ] } } } } } }, "400": { "description": "invalid_request / invalid_json: fix the field indicated by param.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key: check the key, expiry, revocation and environment.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "credits_exhausted / payment_overdue: no credits left this period, or the plan’s last payment failed (url is the invoice). Buy more or change plan in Usage, or pay the invoice, then retry. Older plans: quota_exceeded when the monthly searches run out.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." }, "POXA-Credits-Remaining": { "schema": { "type": "integer" }, "description": "Credits left this period for the whole account, after this call." }, "POXA-Credits-Limit": { "schema": { "type": "integer" }, "description": "Credits this period: the plan’s plus any bought." }, "POXA-Credits-Reset": { "schema": { "type": "integer" }, "description": "When the credits reset, Unix seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_required / account_unavailable: check your account membership.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: check the valuation ID and key owner.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict / request_in_progress: preserve the same key and payload when retrying an in-flight request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large: reduce images below the documented limits.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "unsupported_media_type: send application/json.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "insufficient_data / photo_analysis_too_large: no complete valuation could be returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: obey Retry-After; daily requests reset at 00:00 UTC.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable / limits_unavailable / valuation_unavailable / photo_analysis_unavailable / photo_analysis_failed / request_interrupted: retry after the service recovers.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "valuation_timeout / photo_analysis_timeout: retry later.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/breaker-value/{id}": { "get": { "operationId": "getBreakerValue", "summary": "Retrieve a saved valuation for 30 days", "description": "Only keys belonging to the original key owner, same account, mode and environment can retrieve this result. No credit or daily valuation is used; the minute limit applies.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved valuation. Free: no credit or daily valuation is used.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "POXA-Version": { "schema": { "type": "string" }, "description": "Response contract version." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Account daily cap for this mode. Present on accepted authenticated requests." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Lower of key and account remaining daily requests." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Next UTC midnight, Unix seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" }, "examples": { "sandbox": { "summary": "Synthetic sandbox fixture; runtime-generated.", "value": { "id": "bv_example", "object": "breaker_value", "api_version": "2026-11-03", "mode": "test", "created_at": "2026-10-20T12:00:00.000Z", "expires_at": "2026-11-19T12:00:00.000Z", "reference": "your-stock-reference", "vehicle": { "vin": "WVWZZZAUZFW321566", "reg": "DEMO1", "make": "Demo", "model": "Hatchback", "variant": null, "year": 2015, "title": "Sandbox demonstration vehicle" }, "value": { "currency": "GBP", "vat": "inc", "parts": 4, "low": 952, "average": 1640.5, "horizons": [ { "months": 1, "within_days": 30, "parts": 0, "low": 0, "average": 0 }, { "months": 3, "within_days": 90, "parts": 1, "low": 630, "average": 1020 }, { "months": 6, "within_days": 180, "parts": 2, "low": 840, "average": 1402.5 }, { "months": 9, "within_days": 270, "parts": 4, "low": 952, "average": 1640.5 }, { "months": 12, "within_days": 365, "parts": 4, "low": 952, "average": 1640.5 } ] }, "demand": { "score": 8, "tier": "hot", "model_version": "sold-db-2026-10-08-v1-demand-v7" }, "damage": { "areas": [ { "area": "front_end", "side": "nearside" } ], "images_received": 0, "images_status": "not_requested", "excluded": { "parts": 1, "low": 56, "average": 102 } }, "inventory": { "status": "not_checked_in_test_mode", "systems": [], "as_of": null, "overlap": null }, "parts": [ { "id": "part_1", "name": "Engine", "area": "powertrain", "side": null, "quantity": 1, "oem_numbers": [ "DEMO1" ], "low": 630, "average": 1020, "sold_12m": 40, "active_listings": 2, "demand": { "score": 10, "tier": "hot", "sells_in_days": 38 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_2", "name": "Gearbox", "area": "powertrain", "side": null, "quantity": 1, "oem_numbers": [ "DEMO2" ], "low": 210, "average": 382.5, "sold_12m": 8, "active_listings": 1, "demand": { "score": 6, "tier": "mid", "sells_in_days": 121 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_4", "name": "Door (Right)", "area": "doors", "side": "offside", "quantity": 1, "oem_numbers": [ "DEMO4" ], "low": 42, "average": 85, "sold_12m": 1, "active_listings": 0, "demand": { "score": 5, "tier": "mid", "sells_in_days": 202 }, "photo_assessment": null, "excluded_reason": null }, { "id": "part_5", "name": "Tailgate", "area": "rear", "side": null, "quantity": 1, "oem_numbers": [ "DEMO5" ], "low": 70, "average": 153, "sold_12m": 1, "active_listings": 1, "demand": { "score": 4, "tier": "mid", "sells_in_days": 243 }, "photo_assessment": null, "excluded_reason": null } ], "removed": [ { "id": "part_3", "name": "Headlight (Left)", "area": "front_end", "side": "nearside", "quantity": 1, "oem_numbers": [ "DEMO3" ], "low": 56, "average": 102, "sold_12m": 2, "active_listings": 0, "demand": { "score": 5, "tier": "mid", "sells_in_days": 180 }, "photo_assessment": null, "excluded_reason": "damage_area" }, { "id": "part_6", "name": "Dashboard", "area": "interior", "side": null, "quantity": 1, "oem_numbers": [ "DEMO6" ], "low": 28, "average": 59.5, "sold_12m": 1, "active_listings": 3, "demand": { "score": 3, "tier": "low", "sells_in_days": 333 }, "photo_assessment": null, "excluded_reason": "below_min_part_value" } ], "data": { "priced_at": "2026-10-20T00:00:00Z", "market_stock_as_of": "2026-10-20", "pricing_updated_at": "2026-10-20T00:00:00Z" }, "warnings": [ "Sandbox fixture. These are illustrative values, not a valuation of the supplied vehicle.", "Revenue estimates assume parts are listed now at competitive prices. They are not a sale guarantee or profit forecast.", "Low and average are conservative per-part estimates matching the Breaker Value app; the adjustments are already included. VAT ex applies a 20% adjustment, not a margin-scheme calculation." ] } } } } } }, "400": { "description": "invalid_request / invalid_json: fix the field indicated by param.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key: check the key, expiry, revocation and environment.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_required / account_unavailable: check your account membership.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: check the valuation ID and key owner.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict / request_in_progress: preserve the same key and payload when retrying an in-flight request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large: reduce images below the documented limits.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "unsupported_media_type: send application/json.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "insufficient_data / photo_analysis_too_large: no complete valuation could be returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: obey Retry-After; daily requests reset at 00:00 UTC.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable / limits_unavailable / valuation_unavailable / photo_analysis_unavailable / photo_analysis_failed / request_interrupted: retry after the service recovers.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "valuation_timeout / photo_analysis_timeout: retry later.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Support correlation ID." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait, when provided." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "POXA API key", "description": "Authorization: Bearer . Never put a key in URLs, browser source or client-side apps. Keys are shown once, stored as hashes, expire after 90 days and can be revoked. Dev and production keys are isolated." } }, "schemas": { "DamageArea": { "type": "object", "additionalProperties": false, "required": [ "area" ], "properties": { "area": { "type": "string", "description": "Exclude this damaged area.", "enum": [ "powertrain", "front_end", "doors", "body", "interior", "wheels", "rear", "misc" ] }, "side": { "type": "string", "description": "UK nearside = left; offside = right. Unpositioned or spanning parts are excluded on either side.", "enum": [ "both", "nearside", "offside" ], "default": "both" } } }, "Request": { "type": "object", "additionalProperties": false, "required": [], "properties": { "vin": { "type": "string", "description": "Exactly one of VIN or reg. 17 characters after removing spaces; I, O and Q are invalid.", "pattern": "^(?:\\s*[A-HJ-NPR-Za-hj-npr-z0-9]){17}\\s*$", "maxLength": 100 }, "reg": { "type": "string", "description": "Exactly one of VIN or reg. UK plate, 2–8 letters/digits after removing spaces.", "pattern": "^(?=[\\s\\S]*[A-Za-z])(?=[\\s\\S]*[0-9])(?:\\s*[A-Za-z0-9]){2,8}\\s*$", "maxLength": 100 }, "damage": { "type": "array", "items": { "$ref": "#/components/schemas/DamageArea" }, "maxItems": 24, "default": [], "description": "Optional damaged areas. Can be combined with photos; exclusions are combined once." }, "damage_images": { "type": "array", "items": { "type": "string", "description": "Base64 JPEG, PNG or WebP data URL. Maximum 1 MiB decoded per image. Remote URLs are not accepted.", "maxLength": 1400000, "pattern": "^data:image/(jpeg|png|webp);base64," }, "maxItems": 6, "default": [], "description": "Up to 6 images, 1 MiB each. JSON body at most 9 MiB. Photos are processed in memory and sent to the image-analysis provider; POXA does not save them in valuation history." }, "min_part_value": { "type": "number", "description": "Exclude parts whose conservative low value INCLUDING VAT, rounded to the nearest pound as in the app, is below this amount. Applied before VAT conversion and duplicate selection. Use 0 to disable the minimum.", "minimum": 0, "maximum": 10000, "default": 40 }, "vat": { "type": "string", "description": "inc: displayed market values. ex: divide by 1.20. Not a margin-scheme tax calculation.", "enum": [ "inc", "ex" ], "default": "inc" }, "detail": { "type": "string", "description": "summary omits the parts and removed arrays; all totals and inventory overlap remain.", "enum": [ "full", "summary" ], "default": "full" }, "reference": { "type": "string", "description": "Your stock/lot reference, returned unchanged. Never send secrets or personal details.", "maxLength": 64, "pattern": "^[^\\u0000-\\u001f]*$" } }, "oneOf": [ { "required": [ "vin" ], "not": { "required": [ "reg" ] } }, { "required": [ "reg" ], "not": { "required": [ "vin" ] } } ] }, "Demand": { "type": "object", "additionalProperties": false, "required": [ "score", "tier", "sells_in_days" ], "properties": { "score": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "tier": { "type": "string", "description": "Relative market demand.", "enum": [ "hot", "mid", "low", "unknown" ] }, "sells_in_days": { "type": [ "integer", "null" ], "minimum": 1, "description": "Uncapped estimated days. Null means insufficient demand evidence; values above 365 are excluded from every horizon." } } }, "PhotoAssessment": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "probability_damaged", "visible", "reason" ], "properties": { "probability_damaged": { "type": "number", "description": "Estimated probability as a percentage, not certainty.", "minimum": 0, "maximum": 100 }, "visible": { "type": "boolean" }, "reason": { "type": "string", "description": "Short explanation of the image assessment." } } }, "Part": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "area", "side", "quantity", "oem_numbers", "low", "average", "sold_12m", "active_listings", "demand", "photo_assessment", "excluded_reason" ], "properties": { "id": { "type": "string", "description": "Unique part-line ID in this valuation." }, "name": { "type": "string", "description": "Part name." }, "area": { "type": "string", "description": "Damage group.", "enum": [ "powertrain", "front_end", "doors", "body", "interior", "wheels", "rear", "misc" ] }, "side": { "type": [ "string", "null" ], "enum": [ "nearside", "offside", null ] }, "quantity": { "type": "integer", "const": 1 }, "oem_numbers": { "type": "array", "items": { "type": "string", "description": "OEM number. Alternative numbers on one line do not represent extra pieces." } }, "low": { "type": "number", "description": "Conservative low estimate for this piece, matching the app. The adjustment is already included.", "minimum": 0 }, "average": { "type": "number", "description": "Conservative average estimate for this piece, matching the app. The adjustment is already included.", "minimum": 0 }, "sold_12m": { "type": "number", "description": "Recorded market sales over the pricing dataset’s 12-month window.", "minimum": 0 }, "active_listings": { "type": "number", "description": "Recorded market stock at data.market_stock_as_of.", "minimum": 0 }, "demand": { "$ref": "#/components/schemas/Demand" }, "photo_assessment": { "$ref": "#/components/schemas/PhotoAssessment" }, "excluded_reason": { "type": [ "string", "null" ], "enum": [ null, "damage_area", "damage_image", "below_min_part_value" ] } } }, "Inventory": { "type": "object", "additionalProperties": false, "required": [ "status", "systems", "as_of", "overlap" ], "properties": { "status": { "type": "string", "description": "Only connected has overlap. Other states are unknown, never zero stock.", "enum": [ "connected", "not_connected", "not_checked_in_test_mode", "permission_required", "sync_pending", "unavailable" ] }, "systems": { "type": "array", "items": { "type": "string", "description": "The inventory source selected. Stock comes from one source, so the same stock is never counted twice: a yard system first, then a stock upload, then an online store.", "enum": [ "yard_system", "stock_upload", "online_store" ] } }, "as_of": { "type": [ "string", "null" ], "description": "Snapshot or latest sync time (for a stock upload, when it was uploaded); may be null." }, "overlap": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "parts", "average_value", "percent_of_value", "items" ], "properties": { "parts": { "type": "integer", "minimum": 0 }, "average_value": { "type": "number", "description": "Value of this car’s parts with matching stock; not the value of all stock.", "minimum": 0 }, "percent_of_value": { "type": "number", "description": "Percentage of the car’s total average value overlapping stock.", "minimum": 0, "maximum": 100 }, "not_in_stock": { "type": "integer", "minimum": 0, "description": "Parts in this valuation you have none of." }, "stock_more": { "type": "integer", "minimum": 0, "description": "Parts you have where one more is worth stocking: what you have, plus one more, would all sell within 13 months (a part that sells in about a year counts) (stock_status stock_more)." }, "cover_basis": { "type": "string", "description": "Where the time one part takes to sell comes from. your_sales: your own sales of the part in the last 12 months, divided by the months of sales history you have; a part you have not sold in that time uses its demand.sells_in_days. market: you have no sales of your own, so every part uses its demand.sells_in_days.", "enum": [ "your_sales", "market" ] }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "part_id", "in_stock" ], "properties": { "part_id": { "type": "string", "description": "Part ID from this valuation." }, "in_stock": { "type": "number", "description": "Matching inventory quantity; unidentified OEMs cannot be matched.", "minimum": 0 }, "months_of_stock": { "type": [ "number", "null" ], "minimum": 0, "description": "How long that stock lasts, in months, to 1 decimal place: in_stock × the days one takes to sell (cover_basis). Null when there is no estimate of how fast the part sells; otherwise 0 when you have none." }, "stock_status": { "type": "string", "description": "Looking a fixed 13 months ahead: not_in_stock (you have none), stock_more (what you have, plus one more, would all sell within 13 months (a part that sells in about a year counts)) or in_stock (you have enough, or there is no estimate of how fast the part sells).", "enum": [ "not_in_stock", "stock_more", "in_stock" ] } } } } } } } }, "Response": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "api_version", "mode", "created_at", "expires_at", "reference", "vehicle", "value", "demand", "damage", "inventory", "data", "warnings" ], "properties": { "id": { "type": "string", "description": "Saved valuation ID." }, "object": { "type": "string", "const": "breaker_value" }, "api_version": { "type": "string", "description": "Contract version." }, "mode": { "type": "string", "description": "Test responses are fixtures, never live valuations.", "enum": [ "test", "live" ] }, "created_at": { "type": "string", "description": "UTC creation time.", "format": "date-time" }, "expires_at": { "type": "string", "description": "UTC deletion deadline, 30 days after creation.", "format": "date-time" }, "reference": { "type": [ "string", "null" ], "description": "" }, "vehicle": { "type": "object", "additionalProperties": false, "required": [ "vin", "reg", "make", "model", "variant", "year", "title" ], "properties": { "vin": { "type": [ "string", "null" ], "description": "" }, "reg": { "type": [ "string", "null" ], "description": "" }, "make": { "type": [ "string", "null" ], "description": "" }, "model": { "type": [ "string", "null" ], "description": "" }, "variant": { "type": [ "string", "null" ], "description": "" }, "year": { "type": [ "integer", "null" ], "description": "" }, "title": { "type": [ "string", "null" ], "description": "" } } }, "value": { "type": "object", "additionalProperties": false, "required": [ "currency", "vat", "parts", "low", "average", "horizons" ], "properties": { "currency": { "type": "string", "const": "GBP" }, "vat": { "type": "string", "description": "Requested basis.", "enum": [ "inc", "ex" ] }, "parts": { "type": "integer", "minimum": 0 }, "low": { "type": "number", "description": "Sum of conservative low part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 }, "average": { "type": "number", "description": "Sum of conservative average part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 }, "horizons": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "months", "within_days", "parts", "low", "average" ], "properties": { "months": { "type": "integer", "enum": [ 1, 3, 6, 9, 12 ] }, "within_days": { "type": "integer", "enum": [ 30, 90, 180, 270, 365 ] }, "parts": { "type": "integer", "minimum": 0 }, "low": { "type": "number", "description": "Sum of conservative low part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 }, "average": { "type": "number", "description": "Sum of conservative average part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 } } }, "minItems": 5, "maxItems": 5, "description": "Cumulative revenue for parts estimated to sell within 30, 90, 180, 270 and 365 days from listing now. Not historical lookback windows or probability-weighted forecasts." } } }, "demand": { "type": "object", "additionalProperties": false, "required": [ "score", "tier", "model_version" ], "properties": { "score": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "tier": { "type": "string", "description": "Value-weighted car demand tier.", "enum": [ "hot", "mid", "low", "unknown" ] }, "model_version": { "type": "string", "description": "Demand model revision." } } }, "damage": { "type": "object", "additionalProperties": false, "required": [ "areas", "images_received", "images_status", "excluded" ], "properties": { "areas": { "type": "array", "items": { "$ref": "#/components/schemas/DamageArea" } }, "images_received": { "type": "integer", "minimum": 0, "maximum": 6 }, "images_status": { "type": "string", "description": "Test images are validated but are not sent to a model.", "enum": [ "simulated", "complete", "not_requested" ] }, "excluded": { "type": "object", "additionalProperties": false, "required": [ "parts", "low", "average" ], "properties": { "parts": { "type": "integer", "minimum": 0 }, "low": { "type": "number", "description": "Sum of conservative low part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 }, "average": { "type": "number", "description": "Sum of conservative average part estimates matching the Breaker Value app, in pounds. Already adjusted; do not apply another discount.", "minimum": 0 } } } } }, "inventory": { "$ref": "#/components/schemas/Inventory" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } }, "data": { "type": "object", "additionalProperties": false, "required": [ "priced_at", "market_stock_as_of", "pricing_updated_at" ], "properties": { "priced_at": { "type": "string", "description": "Valuation time." }, "market_stock_as_of": { "type": "string", "description": "Market-stock dataset age. May be a stale-date label." }, "pricing_updated_at": { "type": [ "string", "null" ], "description": "" } } }, "warnings": { "type": "array", "items": { "type": "string", "description": "Coverage and interpretation notes." } } } }, "Credits": { "type": "object", "additionalProperties": true, "required": [ "plan", "total", "used", "remaining", "resetsAt" ], "description": "Your account’s credits this period, shared by everyone on the account. Further fields may be added.", "properties": { "model": { "type": "string", "const": "credits" }, "plan": { "type": "string", "description": "Plan key.", "enum": [ "credits_free", "credits_starter", "credits_growth", "credits_scale" ] }, "planName": { "type": "string", "description": "Plan name." }, "status": { "type": [ "string", "null" ], "description": "Plan payment status: free, active, past_due and so on." }, "isFree": { "type": "boolean" }, "periodStart": { "type": "string", "description": "Start of this period, UTC.", "format": "date-time" }, "periodEnd": { "type": "string", "description": "End of this period, UTC.", "format": "date-time" }, "resetsAt": { "type": "string", "description": "When the credits reset, UTC. Unused credits do not carry over.", "format": "date-time" }, "included": { "type": "integer", "minimum": 0, "description": "Credits from the plan this period." }, "packCredits": { "type": "integer", "minimum": 0, "description": "Extra credits bought this period." }, "total": { "type": "integer", "minimum": 0, "description": "included plus packCredits." }, "used": { "type": "integer", "minimum": 0, "description": "Credits used this period, by everyone on the account." }, "remaining": { "type": "integer", "minimum": 0, "description": "Credits left this period." }, "byChannel": { "type": "object", "additionalProperties": false, "required": [ "web", "extension", "api", "partsfinder" ], "properties": { "web": { "type": "integer", "minimum": 0 }, "extension": { "type": "integer", "minimum": 0 }, "api": { "type": "integer", "minimum": 0 }, "partsfinder": { "type": "integer", "minimum": 0 } } } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Explanation and suggested action." }, "param": { "type": "string", "description": "Invalid field, when relevant." }, "credits": { "$ref": "#/components/schemas/Credits", "description": "credits_exhausted and payment_overdue: your account’s credits this period." }, "url": { "type": "string", "description": "payment_overdue: the invoice to pay, when the key’s owner manages the account’s billing (others are told to ask their account admin).", "format": "uri" }, "request_id": { "type": "string", "description": "Use this ID when contacting support." } } } } } } }, "x-poxa-errors": { "400": "invalid_request / invalid_json: fix the field indicated by param.", "401": "invalid_api_key: check the key, expiry, revocation and environment.", "402": "credits_exhausted / payment_overdue: no credits left this period, or the plan’s last payment failed (url is the invoice). Buy more or change plan in Usage, or pay the invoice, then retry. Older plans: quota_exceeded when the monthly searches run out.", "403": "account_required / account_unavailable: check your account membership.", "404": "not_found: check the valuation ID and key owner.", "409": "idempotency_conflict / request_in_progress: preserve the same key and payload when retrying an in-flight request.", "413": "payload_too_large: reduce images below the documented limits.", "415": "unsupported_media_type: send application/json.", "422": "insufficient_data / photo_analysis_too_large: no complete valuation could be returned.", "429": "rate_limited: obey Retry-After; daily requests reset at 00:00 UTC.", "503": "service_unavailable / limits_unavailable / valuation_unavailable / photo_analysis_unavailable / photo_analysis_failed / request_interrupted: retry after the service recovers.", "504": "valuation_timeout / photo_analysis_timeout: retry later." }, "x-poxa-default-limits": { "credits_per_live_valuation": 1, "daily_live_per_account": 5000, "daily_live_per_account_older_plans": 100, "daily_test_per_account": 1000, "requests_per_minute_per_account": 60, "concurrent_valuations_per_account": 2, "key_expiry_days": 90, "active_keys_per_user": 10, "retention_days": 30 } }