{
  "openapi": "3.0.3",
  "info": {
    "title": "AlgoDriven AU Data APIs",
    "description": "Australia data APIs: VIN Decoding and Pricing AI. Separate packs: EvalExpert, DriveExpert, GCC. Docs: https://developer.algodriven.xyz/au",
    "version": "1.2.0",
    "contact": {
      "name": "AlgoDriven",
      "url": "https://algodriven.xyz"
    }
  },
  "servers": [
    {
      "url": "https://algodriven.io/v1",
      "description": "AU production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "VIN Decode",
      "description": "AU VIN / rego vehicle data (sandbox: use published test VINs)."
    },
    {
      "name": "Pricing AI",
      "description": "AI price prediction + async reasoning poll."
    }
  ],
  "paths": {
    "/vindataext": {
      "post": {
        "tags": [
          "VIN Decode"
        ],
        "summary": "VIN Data Extended (AU)",
        "description": "Returns vehicle details and specifications by VIN or rego+state. AU region keys only.",
        "operationId": "vinDataExtended",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vin": {
                    "type": "string",
                    "description": "17-character VIN"
                  },
                  "rego": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "QLD",
                      "NSW",
                      "ACT",
                      "VIC",
                      "TAS",
                      "NT",
                      "SA",
                      "WA"
                    ]
                  },
                  "clientRef": {
                    "type": "string"
                  },
                  "compReg": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ]
                  },
                  "engineNo": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ]
                  }
                }
              },
              "example": {
                "vin": "WAUZZZ8T6GA014860",
                "clientRef": "demo-1"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vehicle data",
            "content": {
              "application/json": {
                "example": {
                  "VehicleData": {
                    "VIN": "WAUZZZ8T6GA014860",
                    "Make": "Audi",
                    "Model": "A5",
                    "BuildYr": "2015",
                    "MY": "2016",
                    "Body": "Hatchback",
                    "Fuel": "Petrol",
                    "Drive": "Four wheel drive",
                    "Cylinders": "4",
                    "Litres": "2",
                    "Transmission": "Automatic"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/VinDataExtResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or region/allowlist denied"
          },
          "400": {
            "description": "VIN not found / bad request"
          },
          "401": {
            "description": "The `authorization` header is missing.",
            "content": {
              "application/json": {
                "example": {
                  "error": "Api key is misssing"
                }
              }
            }
          }
        }
      }
    },
    "/prediction": {
      "post": {
        "servers": [
          {
            "url": "https://pricingai.algodriven.io/v1"
          }
        ],
        "tags": [
          "Pricing AI"
        ],
        "summary": "Get Price Prediction",
        "description": "Pricing AI prediction by VIN or prior requestId. Pass reasoning=true to kick off async insight bullets.",
        "operationId": "getPricePrediction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "km",
                  "predictDate"
                ],
                "properties": {
                  "vin": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  },
                  "km": {
                    "type": "string"
                  },
                  "predictDate": {
                    "type": "string",
                    "format": "date"
                  },
                  "reasoning": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prediction payload",
            "content": {
              "application/json": {
                "example": {
                  "confidence": "Medium",
                  "prediction_date": "2026-07-16",
                  "prices": {},
                  "currency_symbol": "$",
                  "requestId": "abc123",
                  "reasoning": {
                    "status": "processing",
                    "dealer": null,
                    "customer": null
                  }
                }
              }
            }
          },
          "403": {
            "description": "Access Denied. API key invalid."
          },
          "401": {
            "description": "The `authorization` header is missing.",
            "content": {
              "application/json": {
                "example": {
                  "error": "Api key is misssing"
                }
              }
            }
          }
        }
      }
    },
    "/prediction/reasoning/{requestId}": {
      "get": {
        "servers": [
          {
            "url": "https://pricingai.algodriven.io/v1"
          }
        ],
        "tags": [
          "Pricing AI"
        ],
        "summary": "Poll Pricing AI Reasoning",
        "operationId": "pollPricingAiReasoning",
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reasoning status/payload"
          },
          "403": {
            "description": "Not authorized for this requestId"
          },
          "404": {
            "description": "No prediction found"
          },
          "401": {
            "description": "The `authorization` header is missing.",
            "content": {
              "application/json": {
                "example": {
                  "error": "Api key is misssing"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VehicleData": {
        "type": "object",
        "description": "Decoded AU vehicle attributes returned under `VehicleData`.",
        "properties": {
          "VIN": {
            "type": "string",
            "example": "WAUZZZ8T6GA014860"
          },
          "Make": {
            "type": "string",
            "example": "Audi"
          },
          "Model": {
            "type": "string",
            "example": "A5"
          },
          "BuildYr": {
            "type": "string",
            "example": "2015"
          },
          "MY": {
            "type": "string",
            "example": "2016"
          },
          "Body": {
            "type": "string",
            "example": "Hatchback"
          },
          "Fuel": {
            "type": "string",
            "example": "Petrol"
          },
          "Drive": {
            "type": "string",
            "example": "Four wheel drive"
          },
          "Cylinders": {
            "type": "string",
            "example": "4"
          },
          "Litres": {
            "type": "string",
            "example": "2"
          },
          "Transmission": {
            "type": "string",
            "example": "Automatic"
          }
        }
      },
      "VinDataExtResponse": {
        "type": "object",
        "properties": {
          "VehicleData": {
            "$ref": "#/components/schemas/VehicleData"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "authorization",
        "description": "Must be sent with all client requests. The API key helps the server validate the request source. Sent as-is (no `Bearer` prefix)."
      }
    }
  },
  "x-sandbox": {
    "au_test_vins": [
      "6G1EP5EH6AL460983",
      "1C6RR7FT6MS537299",
      "MMAJLKL10PH006556",
      "5YJSB7E24JF257977"
    ],
    "au_test_regos": [
      "1DLE148",
      "EOB14K",
      "RG595",
      "CGZ017"
    ],
    "au_test_hint": "These VINs and regos return canned vehicle data from `/vindataext` and never reach a paid decoder, so they do not consume real_lookups. Any other VIN or rego consumes one on its first decode and is free on every repeat.",
    "rate_limits_sandbox": {
      "daily": 50,
      "monthly": 500,
      "real_lookups": 20,
      "real_lookups_note": "Counts distinct VINs you decode and Pricing AI predictions, not requests. Repeating a VIN, repeating a decode or prediction for the same VIN is free, so the fixture VINs above never draw it down. This is a lifetime total for the key, not a daily or monthly one, so it does not reset on its own — ask your AlgoDriven contact if you need it cleared. Exceeding it returns 429."
    }
  },
  "x-algodriven-region": "AU"
}