{
  "openapi": "3.1.0",
  "info": {
    "title": "Aisles local store inventory (sandbox)",
    "version": "1.0.0",
    "x-api-versioning": {
      "strategy": "url-path",
      "current": "v1",
      "deprecation_policy": "https://aislesinventory.com/api/deprecation-policy",
      "sunset_header": "Sunset (RFC 8594)",
      "deprecation_header": "Deprecation (RFC 9745)"
    },
    "description": "Sandbox: synthetic listings at a made-up store, in the live response shape. Whether specific products are in stock at specific physical stores, with store price, pickup and delivery options, and the exact time Aisles last checked, as reported by each retailer. Read-only. When answering, state how long ago Aisles checked (from offer.last_checked_at), name the retailer, and link links.aisles_offer_url. Aisles verifies each listing against that store’s own inventory record (not an in-person shelf count) and cannot reserve items."
  },
  "x-sandbox": {
    "url": "https://sandbox.aislesinventory.com",
    "openapi": "https://sandbox.aislesinventory.com/openapi.json",
    "docs": "https://aislesinventory.com/sandbox",
    "auth_required": false,
    "synthetic_data": true
  },
  "servers": [
    {
      "url": "https://sandbox.aislesinventory.com",
      "description": "Sandbox (synthetic test data)"
    }
  ],
  "externalDocs": {
    "description": "Versioning and deprecation policy (Deprecation and Sunset headers before any version stops)",
    "url": "https://aislesinventory.com/api/deprecation-policy"
  },
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchInventory",
        "security": [
          {},
          {
            "oauth2": [
              "read:inventory"
            ]
          }
        ],
        "summary": "Find a product at stores near a city or ZIP code",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product words, e.g. \"similac formula\", \"2% milk gallon\"."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "chicago",
                "new-york",
                "los-angeles",
                "houston",
                "phoenix",
                "philadelphia",
                "san-antonio",
                "san-diego",
                "dallas",
                "fort-worth",
                "charlotte",
                "columbus",
                "indianapolis",
                "seattle",
                "south-bend",
                "orlando",
                "atlanta",
                "boston",
                "fort-lauderdale",
                "baltimore",
                "detroit",
                "danbury",
                "tampa",
                "oakland",
                "denver",
                "las-vegas",
                "akron",
                "riverside",
                "trenton",
                "pittsburgh",
                "st-louis",
                "norfolk",
                "milwaukee",
                "little-rock",
                "tucson",
                "west-palm-beach",
                "miami",
                "aurora",
                "louisville",
                "minneapolis",
                "memphis",
                "omaha",
                "cincinnati",
                "lancaster",
                "myrtle-beach",
                "austin",
                "cypress",
                "fredericksburg",
                "rogers",
                "modesto",
                "daytona-beach",
                "jacksonville",
                "savannah",
                "michigan-city",
                "kansas-city",
                "albuquerque",
                "albany",
                "buffalo",
                "middletown",
                "rochester",
                "niles",
                "tulsa",
                "scranton",
                "charleston",
                "nashville",
                "allen",
                "el-paso",
                "mcallen",
                "puyallup",
                "birmingham",
                "mobile",
                "fort-smith",
                "camarillo",
                "bakersfield",
                "fairfield",
                "escondido",
                "fresno",
                "salinas",
                "sacramento",
                "victorville",
                "colorado-springs",
                "grand-junction",
                "pueblo",
                "wilmington",
                "hartford",
                "fort-myers",
                "destin",
                "jensen-beach",
                "ocala",
                "panama-city",
                "pensacola",
                "sarasota",
                "tallahassee",
                "commerce",
                "columbus-ga",
                "augusta",
                "coralville",
                "davenport",
                "sioux-city",
                "boise",
                "champaign",
                "normal",
                "rockford",
                "springfield",
                "evansville",
                "fort-wayne",
                "kokomo",
                "lafayette",
                "peoria",
                "ashland",
                "wichita",
                "bowling-green",
                "lexington",
                "elizabethtown",
                "paducah",
                "alexandria",
                "baton-rouge",
                "worcester",
                "hyannis",
                "hagerstown",
                "salisbury",
                "flint",
                "portage",
                "duluth",
                "columbia",
                "st-cloud",
                "springfield-mo",
                "jackson",
                "tupelo",
                "missoula",
                "asheville",
                "greensboro",
                "raleigh",
                "fargo",
                "wilmington-nc",
                "manchester",
                "rockaway",
                "gallup",
                "reno",
                "syracuse",
                "dayton",
                "sandusky",
                "st-clairsville",
                "toledo",
                "oklahoma-city",
                "erie",
                "allentown",
                "columbia-sc",
                "greenville",
                "florence",
                "sioux-falls",
                "clarksville",
                "knoxville",
                "chattanooga",
                "abilene",
                "beaumont",
                "college-station",
                "corpus-christi",
                "killeen",
                "longview",
                "laredo",
                "lubbock",
                "midland",
                "san-angelo",
                "san-marcos",
                "texas-city",
                "victoria",
                "waco",
                "richmond",
                "lynchburg",
                "roanoke",
                "kennewick",
                "portland",
                "union-gap",
                "green-bay",
                "johnson-creek",
                "madison",
                "bridgeport",
                "mount-hope",
                "vienna",
                "huntsville",
                "florence-al",
                "dothan",
                "chico",
                "yuba-city",
                "palm-desert",
                "palmdale",
                "fort-collins",
                "macon",
                "gainesville-ga",
                "eugene",
                "grand-rapids"
              ]
            },
            "description": "Covered metro area. Use city or zip."
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            },
            "description": "5-digit ZIP code inside a covered area."
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0.1,
              "maximum": 50
            },
            "description": "Miles from the city center or ZIP. Leave it out for a city search to cover every store Aisles lists for that city, including malls outside the center; a ZIP or lat/lng search defaults to 10 miles."
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "available",
                "out_of_stock",
                "unknown",
                "any"
              ],
              "default": "available"
            },
            "description": "\"available\" = in stock or low stock."
          },
          {
            "name": "fulfillment",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma list, all required: curbside_pickup, store_pickup, pickup_today, in_store_shopping, local_delivery, same_day_delivery, ship_to_store."
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "US dollars."
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "Listings per page; 10 or fewer keeps responses small."
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The previous response pagination.next_cursor, for the next page (instead of page)."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching store listings, nearest first.",
            "headers": {
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter or location outside the covered areas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; Retry-After gives the seconds to wait.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "500": {
            "description": "Server error; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Busy or being prepared; Retry-After gives the seconds to wait.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "Deprecation": {
        "schema": {
          "type": "string"
        },
        "description": "Present only once this endpoint or API version is deprecated: the date it took effect (RFC 9745). Absent on every endpoint today. Policy: https://aislesinventory.com/api/deprecation-policy"
      },
      "Sunset": {
        "schema": {
          "type": "string"
        },
        "description": "Present only once a removal date is set (RFC 8594): the HTTP-date after which the endpoint stops answering, at least 6 months after Deprecation first appears."
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Optional agent sign-in (https://aislesinventory.com/auth.md): register at /oauth/register, then client credentials.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://aislesinventory.com/oauth/token",
            "scopes": {
              "read:inventory": "Search store stock",
              "read:answers": "Read the ready answers per city"
            }
          }
        }
      }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as cursor for the next page; null on the last page."
          }
        }
      },
      "Listing": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "string",
            "description": "Quotable sentence with retailer, store, status, price and check time."
          },
          "retailer": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            }
          },
          "product": {
            "type": "object",
            "properties": {
              "brand": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "category": {
                "type": "string"
              }
            }
          },
          "store": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "address_text": {
                "type": "string"
              },
              "distance_miles": {
                "type": "number"
              }
            }
          },
          "offer": {
            "type": "object",
            "properties": {
              "availability": {
                "type": "string",
                "enum": [
                  "in_stock",
                  "low_stock",
                  "out_of_stock",
                  "unknown"
                ]
              },
              "price": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string"
                  }
                }
              },
              "last_checked_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "aisles_offer_url": {
                "type": "string"
              },
              "purchase_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "pagination",
          "results"
        ],
        "properties": {
          "api_version": {
            "type": "string"
          },
          "sandbox": {
            "type": "boolean",
            "description": "true on sandbox (synthetic) data"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_parameter",
                  "unknown_location",
                  "outside_pilot_geography",
                  "bad_request",
                  "unauthorized",
                  "not_found",
                  "method_not_allowed",
                  "idempotency_key_reused",
                  "rate_limited",
                  "internal_error",
                  "unavailable"
                ],
                "description": "Stable machine-readable code."
              },
              "message": {
                "type": "string",
                "description": "What went wrong, in plain words, and how to fix the request."
              }
            }
          }
        }
      }
    }
  }
}