{"openapi":"3.1.0","info":{"title":"Speckr Customer API","version":"1.0.0","description":"Purchase lookup packages, manage automatic top-ups, and retrieve customer-ready Tesla vehicle specifications."},"servers":[{"url":"https://speckr.com/api/v1"}],"security":[{"customerApiKey":[]}],"paths":{"/openapi.json":{"get":{"security":[],"operationId":"getOpenApi","summary":"Get the customer API contract","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/packages":{"get":{"operationId":"listPackages","summary":"List purchasable packages","responses":{"200":{"description":"Package catalog","content":{"application/json":{"schema":{"type":"object","required":["object","data"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"operationId":"getCredits","summary":"Get available credits","responses":{"200":{"description":"Credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalance"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkouts":{"post":{"operationId":"createCheckout","summary":"Create a hosted package Checkout","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package_key"],"additionalProperties":false,"properties":{"package_key":{"type":"string"}}}}}},"responses":{"201":{"description":"Hosted Stripe Checkout URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/vehicle-specs":{"post":{"operationId":"fetchVehicleSpecs","summary":"Retrieve translated vehicle specifications","description":"Consumes one lookup credit after the result is prepared successfully. The vehicle is added to My Vehicles.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vin"],"additionalProperties":false,"properties":{"vin":{"type":"string","minLength":17,"maxLength":17}}}}}},"responses":{"200":{"description":"CustomerVehicleSpecsV1","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerVehicleSpecsV1"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auto-top-up":{"get":{"operationId":"getAutoTopUp","summary":"Get automatic top-up settings","responses":{"200":{"description":"Current rule and monthly spend","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticTopUp"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"configureAutoTopUp","summary":"Configure automatic top-up","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package_key"],"additionalProperties":false,"properties":{"package_key":{"type":"string"},"threshold_percent":{"type":"integer","enum":[10,20,30],"default":10},"monthly_cap_cents":{"type":"integer","minimum":1,"maximum":2147483647}}}}}},"responses":{"200":{"description":"Active rule or payment setup URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticTopUp"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"disableAutoTopUp","summary":"Disable automatic top-up immediately","responses":{"200":{"description":"Disabled rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticTopUp"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported VIN or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Retriable dependency failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"customerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"spk_live_…"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200},"description":"Unique request key retained for 24 hours."}},"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"Package":{"type":"object","required":["package_key","name","credits","price","credits_expire_after_days"],"additionalProperties":false,"properties":{"package_key":{"type":"string"},"name":{"type":"string"},"credits":{"type":"integer","minimum":1},"price":{"type":"object","required":["amount_cents","currency","display"],"additionalProperties":false,"properties":{"amount_cents":{"type":"integer","minimum":1},"currency":{"const":"usd"},"display":{"type":"string"}}},"credits_expire_after_days":{"const":30}}},"CreditBalance":{"type":"object","required":["object","available_credits","auto_top_up"],"additionalProperties":false,"properties":{"object":{"const":"credit_balance"},"available_credits":{"type":"integer","minimum":0},"auto_top_up":{"type":"object","required":["enabled","status"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"status":{"type":"string"}}}}},"Checkout":{"type":"object","required":["object","checkout_url","package_key"],"additionalProperties":false,"properties":{"object":{"const":"checkout"},"checkout_url":{"type":"string","format":"uri"},"package_key":{"type":"string"}}},"AutomaticTopUp":{"type":"object","required":["object","enabled","status","package_key","threshold_percent","threshold_credits","monthly_cap","monthly_spend","payment_method"],"additionalProperties":false,"properties":{"object":{"const":"automatic_top_up"},"enabled":{"type":"boolean"},"status":{"type":"string"},"package_key":{"type":["string","null"]},"threshold_percent":{"type":["integer","null"],"enum":[10,20,30,null]},"threshold_credits":{"type":["integer","null"],"minimum":0},"monthly_cap":{"oneOf":[{"type":"object","required":["amount_cents","currency"],"additionalProperties":false,"properties":{"amount_cents":{"type":"integer","minimum":0},"currency":{"const":"usd"}}},{"type":"null"}]},"monthly_spend":{"type":"object","required":["amount_cents","currency"],"additionalProperties":false,"properties":{"amount_cents":{"type":"integer","minimum":0},"currency":{"const":"usd"}}},"payment_method":{"oneOf":[{"type":"object","required":["brand","last4"],"additionalProperties":false,"properties":{"brand":{"type":"string"},"last4":{"type":"string","pattern":"^[0-9]{4}$"}}},{"type":"null"}]},"setup_url":{"type":"string","format":"uri"}}},"CustomerVehicleSpecsV1":{"type":"object","required":["object","version","vin","title","vehicle","summary","battery","range_and_charging","sections"],"additionalProperties":false,"properties":{"object":{"const":"vehicle_specs"},"version":{"const":"2026-09-01"},"vin":{"type":"string"},"title":{"type":"string"},"vehicle":{"type":"object","required":["year","make","model","trim"],"additionalProperties":false,"properties":{"year":{"type":["string","null"]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trim":{"type":["string","null"]}}},"summary":{"type":"object","required":["production_date","factory","wheels","paint","interior","supercharging"],"additionalProperties":false,"properties":{"production_date":{"type":["string","null"]},"factory":{"type":["string","null"]},"wheels":{"type":["string","null"]},"paint":{"type":["string","null"]},"interior":{"type":["string","null"]},"supercharging":{"type":["string","null"]}}},"battery":{"type":"object","required":["state_of_health_percent","usable_capacity","original_capacity_kwh","capacity_summary","last_measured"],"additionalProperties":false,"properties":{"state_of_health_percent":{"type":["number","null"]},"usable_capacity":{"type":["string","null"]},"original_capacity_kwh":{"type":["number","null"]},"capacity_summary":{"type":["string","null"]},"last_measured":{"type":["string","null"]}}},"range_and_charging":{"type":"object","required":["rows","wheel_rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","items":{"type":"object","required":["key","label","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}},"wheel_rows":{"type":"array","items":{"type":"object","required":["wheel_size","range","city_range","highway_range","mpge_combined","mpge_city","mpge_highway","efficiency","efficiency_wh_per_mile","fuel_cost","annual_electricity_cost","annual_gas_savings","level_2_charging","supercharger_0_to_80","supercharger_0_to_100"],"additionalProperties":false,"properties":{"wheel_size":{"type":"string"},"range":{"type":["string","null"]},"city_range":{"type":["string","null"]},"highway_range":{"type":["string","null"]},"mpge_combined":{"type":["string","null"]},"mpge_city":{"type":["string","null"]},"mpge_highway":{"type":["string","null"]},"efficiency":{"type":["string","null"]},"efficiency_wh_per_mile":{"type":["string","null"]},"fuel_cost":{"type":["string","null"]},"annual_electricity_cost":{"type":["string","null"]},"annual_gas_savings":{"type":["string","null"]},"level_2_charging":{"type":["string","null"]},"supercharger_0_to_80":{"type":["string","null"]},"supercharger_0_to_100":{"type":["string","null"]}}}}}},"sections":{"type":"array","items":{"type":"object","required":["key","title","rows"],"additionalProperties":false,"properties":{"key":{"enum":["technology","drivetrain","options"]},"title":{"type":"string"},"rows":{"type":"array","items":{"type":"object","required":["key","label","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}}}}}