{
  "openapi": "3.0.3",
  "info": {
    "title": "Average Rent Data API",
    "version": "1.0.0",
    "description": "Unit-level US apartment rent data, refreshed daily: city averages, per-bedroom breakdowns, market history, per-unit price cuts, and building-level pricing with concessions. Subscribe at https://average-rent.com/developers/ to get an API key.",
    "contact": {
      "email": "jp@miningstore.com",
      "url": "https://average-rent.com/developers/"
    },
    "termsOfService": "https://average-rent.com/terms/"
  },
  "servers": [
    {
      "url": "https://average-rent.com/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer ar_live_..."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "x-plans": {
    "developer": {
      "price_usd_month": 49,
      "requests_per_month": 25000,
      "requests_per_minute": 60
    },
    "growth": {
      "price_usd_month": 199,
      "requests_per_month": 250000,
      "requests_per_minute": 300
    },
    "scale": {
      "price_usd_month": 499,
      "requests_per_month": 1000000,
      "requests_per_minute": 600
    }
  },
  "paths": {
    "/cities": {
      "get": {
        "summary": "List covered cities",
        "description": "Every covered city with inventory counts and current market average.",
        "parameters": [],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/cities/{city}/stats": {
      "get": {
        "summary": "City market stats",
        "description": "Average/min/max rent plus per-bedroom breakdown.",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,60}$"
            },
            "description": "City slug, e.g. austin-tx. GET /cities lists all covered slugs."
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/cities/{city}/history": {
      "get": {
        "summary": "City market history",
        "description": "Daily market-average series (outlier-trimmed).",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,60}$"
            },
            "description": "City slug, e.g. austin-tx. GET /cities lists all covered slugs."
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 7,
              "maximum": 365,
              "default": 90
            }
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/cities/{city}/price-cuts": {
      "get": {
        "summary": "Recent per-unit price cuts",
        "description": "Units whose asking rent dropped in the trailing 7 days.",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,60}$"
            },
            "description": "City slug, e.g. austin-tx. GET /cities lists all covered slugs."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/cities/{city}/properties": {
      "get": {
        "summary": "City property directory",
        "description": "Paginated buildings with pricing summary.",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,60}$"
            },
            "description": "City slug, e.g. austin-tx. GET /cities lists all covered slugs."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/properties/{id}": {
      "get": {
        "summary": "Property detail",
        "description": "One building with every currently listed unit: rent, plan, sqft, fees, concessions, availability.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Property id from /cities/{city}/properties."
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/properties/{id}/history": {
      "get": {
        "summary": "Property price history",
        "description": "Daily min/avg/max/median snapshots for one building.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Property id from /cities/{city}/properties."
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 7,
              "maximum": 365,
              "default": 180
            }
          }
        ],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    },
    "/me": {
      "get": {
        "summary": "Key introspection",
        "description": "Plan, limits, and month-to-date usage for the calling key.",
        "parameters": [],
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Body is { data, meta }."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limit or monthly quota reached. See X-RateLimit-* and X-Quota-* headers."
          }
        }
      }
    }
  }
}