{
    "openapi": "3.0.3",
    "info": {
        "title": "CarLogs Vehicle Data API",
        "version": "1.0.0",
        "description": "Vehicle data and full history reports for VINs and US/Canada licence plates. Lookups cost 1 prepaid credit; full history reports cost report credits ($9.95 each), buyable in-protocol via /checkout. Built for AI agents. Vehicle data only — never owner information."
    },
    "servers": [
        {
            "url": "https://carlogs.xyz/api/v1"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearer": {
                "type": "http",
                "scheme": "bearer",
                "description": "API key from https://carlogs.xyz/developers"
            }
        }
    },
    "paths": {
        "/vehicle/{vin}": {
            "get": {
                "summary": "Everything on record for one VIN",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "vin",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 17,
                            "maxLength": 17
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Vehicle data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Out of credits",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "VIN could not be decoded (not charged)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit: 60 requests per minute",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/model/{make}/{model}/{year}": {
            "get": {
                "summary": "Model-year data: recalls, complaints, ratings, MPG, value",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "make",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "model",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "year",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Model-year data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Out of credits",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Model year not on record (not charged)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/report/{vin}": {
            "get": {
                "summary": "Full vehicle history report (title, odometer, salvage, liens, valuation) as JSON — costs one report credit",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "vin",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 17,
                            "maxLength": 17
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "History report (X-Report-Credits-Remaining header)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Report compiling — retry after `retry_in` seconds (not charged again)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "No report credits — body has a `buy` block; POST /checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "VIN not found or not US-titled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Provider unavailable — retry later",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/report": {
            "get": {
                "summary": "Full history report for a plate match, by report token (no VIN needed) — costs one report credit",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "pt",
                        "in": "query",
                        "required": true,
                        "description": "report_token from /plate",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "History report (reveals the VIN)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "No report credits — POST /checkout",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Invalid token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plate": {
            "get": {
                "summary": "Resolve a US/Canada licence plate to a vehicle teaser (year/make/model, no VIN) + a report_token — costs one lookup credit on a match",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "us",
                                "ca"
                            ]
                        }
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "required": true,
                        "description": "2-letter state/province",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "plate",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Match: teaser + report_token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Out of lookup credits",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No match (not charged)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Lookups at capacity",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/checkout": {
            "post": {
                "summary": "Buy report credits — returns a Stripe checkout_url for a human to pay, then poll /balance",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "quantity": {
                                        "type": "integer",
                                        "description": "report credits to buy"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "{checkout_url, session_id, amount_usd, poll}",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Payments unavailable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/balance": {
            "get": {
                "summary": "Current lookup credits, Pro allowance and report credits",
                "security": [
                    {
                        "bearer": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Balances + report pack prices",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}