{
  "openapi": "3.1.0",
  "info": {
    "title": "SiteFinderAI API",
    "version": "1.0.0",
    "description": "Find ranked, callable Australian sites for vending machines, ATMs, ice machines and photo booths. Each site returned by /site-search consumes one lookup from the account's plan or top-up balance."
  },
  "servers": [
    {
      "url": "https://sitefinderai.com/api/public/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sfa_live_*"
      }
    }
  },
  "paths": {
    "/site-search": {
      "post": {
        "operationId": "siteSearch",
        "summary": "Find ranked vending sites near an Australian location",
        "description": "Example: find 20 blue-collar sites in Ipswich. Consumes one lookup per site returned. Send an Idempotency-Key header to make retries free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "location"
                ],
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "Australian town, suburb, postcode or state (e.g. 'Ipswich QLD')."
                  },
                  "machineType": {
                    "type": "string",
                    "enum": [
                      "combo",
                      "coffee",
                      "food",
                      "drink",
                      "snack",
                      "ppe",
                      "cigarette",
                      "atm",
                      "ice_machine",
                      "photobooth"
                    ],
                    "default": "combo"
                  },
                  "collarType": {
                    "type": "string",
                    "enum": [
                      "white_collar",
                      "blue_collar"
                    ],
                    "nullable": true
                  },
                  "businessCategories": {
                    "type": "array",
                    "maxItems": 4,
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 4 categories, e.g. warehouse, factory, distribution_centre."
                  },
                  "radiusM": {
                    "type": "integer",
                    "default": 500,
                    "minimum": 250,
                    "maximum": 2000
                  },
                  "limit": {
                    "type": "integer",
                    "default": 10,
                    "minimum": 1,
                    "maximum": 20
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked sites with competitor scan and pitch summary"
          },
          "401": {
            "description": "Missing or revoked API key"
          },
          "402": {
            "description": "No lookups left, or the account needs a paid seat"
          },
          "429": {
            "description": "Rate limited — honour Retry-After"
          }
        }
      }
    },
    "/sites/{siteId}": {
      "get": {
        "operationId": "getSite",
        "summary": "Fetch one saved site with its confidence breakdown",
        "parameters": [
          {
            "name": "siteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Site detail"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Remaining plan lookups, top-up balance and reset date",
        "responses": {
          "200": {
            "description": "Usage summary"
          }
        }
      }
    },
    "/coverage": {
      "get": {
        "operationId": "getCoverage",
        "summary": "Supported states, machine types and categories (free, no lookups)",
        "security": [],
        "responses": {
          "200": {
            "description": "Coverage metadata"
          }
        }
      }
    }
  }
}