{
  "openapi": "3.0.3",
  "info": {
    "title": "Dubuy.ai Pro API",
    "version": "1.0.0",
    "description": "Read-only access to Dubai community intelligence built on official Dubai Land Department (DLD) transactions and Ejari rental contracts. Requires a Pro API key (Authorization: Bearer dub_live_...). Get one at https://dubuy.ai/account/api-keys/. Rate limit: 60 requests/minute per key (default; may vary per key). Breaking changes bump the path to /api/v2.",
    "contact": { "name": "Dubuy.ai", "email": "hello@dubuy.ai", "url": "https://dubuy.ai/developers/" }
  },
  "servers": [{ "url": "https://dubuy.ai/api/v1" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Pro API key of the form dub_live_… . Send as `Authorization: Bearer dub_live_…` or the `X-API-Key` header."
      }
    },
    "parameters": {
      "slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Community slug, e.g. `dubai-marina`." },
      "limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Max items to return." },
      "propertyType": { "name": "property_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["apartment", "villa"] } }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key." },
      "PaymentRequired": { "description": "Key is valid but the account is not on an active Pro plan." },
      "RateLimited": { "description": "Per-key rate limit exceeded. See Retry-After and X-RateLimit-* headers." },
      "NotFound": { "description": "Resource not found." }
    }
  },
  "paths": {
    "/communities": {
      "get": {
        "summary": "List communities",
        "description": "All Dubai communities with headline stats + DLD-derived market-temperature percentile.",
        "parameters": [{ "$ref": "#/components/parameters/propertyType" }, { "$ref": "#/components/parameters/limit" }],
        "responses": { "200": { "description": "Array of community summaries." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/communities/{slug}": {
      "get": {
        "summary": "Community profile",
        "description": "Full profile — stats, bedroom breakdown, Ejari rents, commute times, pulse.",
        "parameters": [{ "$ref": "#/components/parameters/slug" }],
        "responses": { "200": { "description": "Full community record." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/communities/{slug}/pulse": {
      "get": {
        "summary": "Community pulse",
        "description": "Historical discussion record — aspect breakdown and paraphrased pull quotes from a dated 2021–2026 archive, plus a separate DLD-derived market-temperature score.",
        "parameters": [{ "$ref": "#/components/parameters/slug" }],
        "responses": { "200": { "description": "Market pulse and historical discussion record." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/communities/{slug}/trends": {
      "get": {
        "summary": "Price trends",
        "description": "Annual median PSF (2020–2026) with total growth % and CAGR.",
        "parameters": [{ "$ref": "#/components/parameters/slug" }],
        "responses": { "200": { "description": "Annual PSF series." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/search": {
      "get": {
        "summary": "Filter communities",
        "parameters": [
          { "$ref": "#/components/parameters/propertyType" },
          { "name": "min_psf_aed", "in": "query", "schema": { "type": "number" } },
          { "name": "max_psf_aed", "in": "query", "schema": { "type": "number" } },
          { "name": "min_price_aed", "in": "query", "schema": { "type": "number" } },
          { "name": "max_price_aed", "in": "query", "schema": { "type": "number" } },
          { "name": "min_yoy_pct", "in": "query", "schema": { "type": "number" } },
          { "name": "min_sentiment_percentile", "in": "query", "schema": { "type": "number" } },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "Matching communities." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } }
      }
    },
    "/compare": {
      "get": {
        "summary": "Compare communities",
        "parameters": [{ "name": "slugs", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated slugs (2–5), e.g. `dubai-marina,jvc`." }],
        "responses": { "200": { "description": "Side-by-side comparison." }, "400": { "description": "Fewer than 2 or more than 5 slugs." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/projects": {
      "get": {
        "summary": "Top projects",
        "parameters": [
          { "name": "area", "in": "query", "schema": { "type": "string" } },
          { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["growth", "volume"] } },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "Ranked projects." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/developers/{name}": {
      "get": {
        "summary": "Developer profile",
        "description": "Curated rating + RERA-registered projects for a Dubai developer.",
        "parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Developer record." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    }
  }
}