{
  "openapi": "3.1.0",
  "info": {
    "title": "Dubuy Data API",
    "version": "2.0.0",
    "description": "Safe-only Dubai property intelligence derived from source-labelled DLD, Ejari, and official registry data. Row-level transactions and listing-provider-derived intelligence are not exposed.",
    "termsOfService": "https://dubuy.ai/data/terms/",
    "contact": { "name": "Dubuy Data", "email": "data@dubuy.ai", "url": "https://dubuy.ai/data/" },
    "license": { "name": "Commercial Dubuy Data API terms", "url": "https://dubuy.ai/data/licensing/" }
  },
  "servers": [{ "url": "https://dubuy.ai/api/v1", "description": "Production" }],
  "tags": [
    { "name": "Metadata" }, { "name": "Market" }, { "name": "Communities" },
    { "name": "Projects" }, { "name": "Developers" }, { "name": "Intelligence" }
  ],
  "paths": {
    "/": {
      "get": { "tags": ["Metadata"], "summary": "API catalog", "security": [], "responses": { "200": { "description": "Capability catalog" } } }
    },
    "/meta": {
      "get": { "tags": ["Metadata"], "summary": "Platform metadata", "security": [], "responses": { "200": { "description": "Plans, endpoint units, and dataset governance" } } }
    },
    "/data-freshness": {
      "get": { "tags": ["Metadata"], "summary": "Dataset freshness", "security": [], "responses": { "200": { "description": "Source and last-success dates" } } }
    },
    "/market/stats": {
      "get": { "tags": ["Market"], "summary": "Citywide market statistics", "x-dubuy-units": 1, "responses": { "200": { "description": "DLD-derived citywide counts, medians, and coverage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }
    },
    "/communities": {
      "get": { "tags": ["Communities"], "summary": "List communities", "x-dubuy-units": 1, "parameters": [{ "$ref": "#/components/parameters/PropertyType" }, { "$ref": "#/components/parameters/Limit" }], "responses": { "200": { "description": "Community summaries" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }
    },
    "/communities/{slug}": {
      "get": { "tags": ["Communities"], "summary": "Community profile", "x-dubuy-units": 2, "parameters": [{ "$ref": "#/components/parameters/Slug" }], "responses": { "200": { "description": "Normalized profile" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/communities/{slug}/properties": {
      "get": { "tags": ["Communities"], "summary": "Community property catalog", "x-dubuy-units": 2, "parameters": [{ "$ref": "#/components/parameters/Slug" }], "responses": { "200": { "description": "Official and transaction-backed property catalog; listing observations, editorial research, and floor-plan assets are excluded" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/communities/{slug}/pulse": {
      "get": { "tags": ["Communities"], "summary": "Community pulse", "x-dubuy-units": 2, "parameters": [{ "$ref": "#/components/parameters/Slug" }], "responses": { "200": { "description": "Dated discussion context and market temperature" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/communities/{slug}/trends": {
      "get": { "tags": ["Communities"], "summary": "Community price trends", "x-dubuy-units": 2, "parameters": [{ "$ref": "#/components/parameters/Slug" }], "responses": { "200": { "description": "Annual PSF and growth history" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/communities/{slug}/as-of": {
      "get": { "tags": ["Communities"], "summary": "Historical community aggregate snapshot", "description": "Returns Dubuy aggregate metrics observed on or closest before the requested date. Transaction rows are never returned.", "x-dubuy-units": 5, "parameters": [
        { "$ref": "#/components/parameters/Slug" },
        { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }
      ], "responses": { "200": { "description": "Historical aggregate community metrics" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/search": {
      "get": { "tags": ["Communities"], "summary": "Screen communities", "x-dubuy-units": 1, "parameters": [
        { "$ref": "#/components/parameters/PropertyType" }, { "$ref": "#/components/parameters/Limit" },
        { "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" } }
      ], "responses": { "200": { "description": "Matching communities" }, "400": { "$ref": "#/components/responses/InvalidRequest" } } }
    },
    "/compare": {
      "get": { "tags": ["Communities"], "summary": "Compare communities", "x-dubuy-units": 4, "parameters": [{ "name": "slugs", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two to five comma-separated slugs" }], "responses": { "200": { "description": "Comparable community profiles" }, "400": { "$ref": "#/components/responses/InvalidRequest" } } }
    },
    "/projects": {
      "get": { "tags": ["Projects"], "summary": "Search official projects", "description": "Registry mode is default. Supplying sort_by=growth|volume returns the legacy performance ranking.", "x-dubuy-units": 2, "parameters": [
        { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "developer", "in": "query", "schema": { "type": "string" } },
        { "name": "area", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } },
        { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["growth", "volume"] } },
        { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }
      ], "responses": { "200": { "description": "Cursor-paginated project records" } } }
    },
    "/projects/{id}": {
      "get": { "tags": ["Projects"], "summary": "Project detail", "x-dubuy-units": 2, "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DLD project number or normalized name" }], "responses": { "200": { "description": "Official registry record and matched performance history" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/developers": {
      "get": { "tags": ["Developers"], "summary": "Search developers", "x-dubuy-units": 2, "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }], "responses": { "200": { "description": "Cursor-paginated RERA developer records" } } }
    },
    "/developers/{name}": {
      "get": { "tags": ["Developers"], "summary": "Developer profile", "x-dubuy-units": 2, "parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Curated rating and source-labelled registry evidence" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/rental-yields": {
      "get": { "tags": ["Market"], "summary": "Rental yields", "x-dubuy-units": 2, "parameters": [{ "name": "community", "in": "query", "schema": { "type": "string" } }, { "name": "min_yield_pct", "in": "query", "schema": { "type": "number" } }, { "$ref": "#/components/parameters/Limit" }], "responses": { "200": { "description": "Ejari-derived yields by community and bedroom" } } }
    },
    "/intelligence/community/{slug}": {
      "get": { "tags": ["Intelligence"], "summary": "Decision-ready community intelligence", "x-dubuy-units": 5, "parameters": [{ "$ref": "#/components/parameters/Slug" }], "responses": { "200": { "description": "Profile, investability, forecast, and fragility bundle" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/intelligence/investment-screen": {
      "get": { "tags": ["Intelligence"], "summary": "Investment screen", "x-dubuy-units": 5, "parameters": [
        { "name": "min_score", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "min_yield_pct", "in": "query", "schema": { "type": "number" } },
        { "name": "max_price_aed", "in": "query", "schema": { "type": "number" } }, { "$ref": "#/components/parameters/PropertyType" }, { "$ref": "#/components/parameters/Limit" }
      ], "responses": { "200": { "description": "Ranked community results with signal drivers" }, "400": { "$ref": "#/components/responses/InvalidRequest" } } }
    }
  },
  "components": {
    "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "dub_test_... or dub_live_...", "description": "Create a key at https://dubuy.ai/account/api-keys/" } },
    "parameters": {
      "Slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical community slug or recognized alias" },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
      "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } },
      "PropertyType": { "name": "property_type", "in": "query", "schema": { "type": "string", "enum": ["apartment", "villa", "mixed"] } }
    },
    "responses": {
      "Unauthorized": { "description": "Missing, invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "Environment or dataset is not in the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "InvalidRequest": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Per-minute limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } }, "documentation_url": { "type": "string", "format": "uri" } } },
      "MarketStats": { "type": "object", "required": ["as_of", "coverage", "source", "citywide"], "properties": { "as_of": { "type": "string", "format": "date" }, "coverage": { "type": "object" }, "source": { "type": "string" }, "total_registered_records": { "type": "integer" }, "matched_communities": { "type": "integer" }, "citywide": { "type": "object" }, "transaction_types": { "type": "object" }, "market_overview": { "type": "object" }, "methodology": { "type": "string" } } }
    }
  },
  "security": [{ "ApiKey": [] }]
}