{
  "openapi": "3.1.0",
  "info": {
    "title": "VRTO Public Directory API",
    "version": "1.0.0",
    "description": "Read-only access to VRTO's rent-to-own store directory. Returns the same public directory data rendered on vrto.com. No authentication is required and no personal data is exposed. Write endpoints (lead capture, store submissions, analytics) are intentionally not part of this API and are disallowed in robots.txt.",
    "contact": {
      "url": "https://www.vrto.com/contact"
    },
    "license": {
      "name": "Directory data provided for reference use",
      "url": "https://www.vrto.com/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://www.vrto.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchDirectory",
        "summary": "Search the retail rent-to-own directory",
        "description": "Typeahead search across cities, companies and store locations in the retail directory. Rate limited to 60 requests per minute.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search term: a city, company or store name.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching directory entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests per minute)."
          }
        }
      }
    },
    "/api/sheds/search": {
      "get": {
        "operationId": "searchShedDealers",
        "summary": "Search the shed and portable-building dealer directory",
        "description": "Typeahead search scoped to the sheds vertical, so a sheds visitor is never returned retail results. Rate limited to 60 requests per minute.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search term: a city, dealer or state.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching dealer directory entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests per minute)."
          }
        }
      }
    },
    "/api/companies": {
      "get": {
        "operationId": "listCompanies",
        "summary": "List rent-to-own operators",
        "description": "Operators in the retail directory with at least one open location. 25 per page, rate limited to 20 requests per minute.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter US state code.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Filter by company or brand name.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching operators.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyListResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (20 requests per minute)."
          },
          "422": {
            "description": "Invalid parameters. JSON clients (Accept: application/json) receive 422; other clients are redirected."
          }
        }
      }
    },
    "/api/locations": {
      "get": {
        "operationId": "listLocations",
        "summary": "List store locations",
        "description": "Open store locations, filterable by company, state or city. 25 per page, rate limited to 20 requests per minute.",
        "parameters": [
          {
            "name": "company",
            "in": "query",
            "required": false,
            "description": "Company slug, as returned by /api/companies.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching locations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationListResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (20 requests per minute)."
          },
          "422": {
            "description": "Invalid parameters. JSON clients (Accept: application/json) receive 422; other clients are redirected."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        },
        "required": [
          "results"
        ]
      },
      "SearchResult": {
        "type": "object",
        "description": "A directory entry. Fields present depend on the entry type.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "city",
              "company",
              "store"
            ],
            "description": "The kind of directory entry."
          },
          "name": {
            "type": "string",
            "description": "Display name, e.g. \"Columbus, OH\"."
          },
          "slug": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "description": "Two-letter US state code."
          },
          "state_slug": {
            "type": "string"
          },
          "store_count": {
            "type": "integer",
            "description": "Open store locations associated with this entry."
          },
          "url": {
            "type": "string",
            "description": "Path to the corresponding page on vrto.com."
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "last_page": {
            "type": "integer"
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "store_count": {
            "type": "integer"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "review_count": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "company_name": {
            "type": "string"
          },
          "company_slug": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "address": {
            "type": "string"
          },
          "address2": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "review_count": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          },
          "is_primary": {
            "type": "boolean"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CompanyListResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Company"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "LocationListResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Location"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      }
    }
  }
}