{
  "openapi": "3.0.3",
  "info": {
    "title": "Upah.ph public API",
    "version": "1.0.0",
    "description": "Public, read-mostly endpoints of the Upah.ph Philippine property-sales marketplace. Authenticated account, owner, agent and admin routes are intentionally excluded — this document covers what a partner or crawler can call without credentials. All responses are JSON unless noted.",
    "contact": { "url": "https://upah.ph/developers" }
  },
  "servers": [{ "url": "https://upah.ph" }],
  "paths": {
    "/api/properties": {
      "get": {
        "summary": "List live property offers",
        "parameters": [
          { "name": "ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated offer ids — returns only those, in requested order" }
        ],
        "responses": { "200": { "description": "{ properties: Offer[], agents: map }" } }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Filtered search over live listings",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free text — matches city, area, title, developer, amenities" },
          { "name": "city", "in": "query", "schema": { "type": "string" } },
          { "name": "near", "in": "query", "schema": { "type": "string", "enum": ["1"] }, "description": "Widen city to its whole region" },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["Ready for occupancy", "Pre-selling", "Rent-to-own"] } },
          { "name": "type", "in": "query", "schema": { "type": "string" } },
          { "name": "payment", "in": "query", "schema": { "type": "string" } },
          { "name": "minPrice", "in": "query", "schema": { "type": "integer" } },
          { "name": "maxPrice", "in": "query", "schema": { "type": "integer" } },
          { "name": "minBeds", "in": "query", "schema": { "type": "integer" } },
          { "name": "maxBeds", "in": "query", "schema": { "type": "integer" } },
          { "name": "minBaths", "in": "query", "schema": { "type": "integer" } },
          { "name": "minSqm", "in": "query", "schema": { "type": "integer" } },
          { "name": "maxSqm", "in": "query", "schema": { "type": "integer" } },
          { "name": "developer", "in": "query", "schema": { "type": "string" } },
          { "name": "openHouse", "in": "query", "schema": { "type": "string" }, "description": "1 — only upcoming open houses" },
          { "name": "reduced", "in": "query", "schema": { "type": "string" }, "description": "1 — only price-reduced listings" },
          { "name": "floodSafe", "in": "query", "schema": { "type": "string" }, "description": "1 — excludes declared high flood risk" },
          { "name": "minPpu", "in": "query", "schema": { "type": "integer" }, "description": "Min price per m²" },
          { "name": "maxPpu", "in": "query", "schema": { "type": "integer" } },
          { "name": "amenity", "in": "query", "schema": { "type": "string" }, "description": "Repeatable or comma-separated feature-filter keys (pool, parking, petfriendly, furnished, …)" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["price:asc", "price:desc", "newest", "sqm:asc", "sqm:desc", "ppu:asc", "ppu:desc"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer" } },
          { "name": "page", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "{ properties: Offer[], total: number }" } }
      }
    },
    "/api/suggest": {
      "get": {
        "summary": "Search-box autocomplete",
        "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "{ suggestions: [{kind,label}] }" } }
      }
    },
    "/api/stats": {
      "get": { "summary": "Marketplace aggregates (listings, cities, medians)", "responses": { "200": { "description": "stats object" } } }
    },
    "/api/trends": {
      "get": {
        "summary": "Monthly market snapshots per city+type",
        "parameters": [{ "name": "city", "in": "query", "schema": { "type": "string" }, "description": "city key — returns a type→series map" }],
        "responses": { "200": { "description": "{ cities } or { city, series }" } }
      }
    },
    "/api/estimate": {
      "get": {
        "summary": "City+type valuation estimate with honest national fallback",
        "parameters": [
          { "name": "city", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "{ estimate: {scope,medianPsqm,p25,p75,n}, cities }" }, "400": { "description": "unknown city/type" } }
      }
    },
    "/api/agents": { "get": { "summary": "Public owner/agent directory", "responses": { "200": { "description": "{ agents }" } } } },
    "/api/agents/{id}": { "get": { "summary": "Public agent profile + reviews", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "profile" }, "404": { "description": "unknown agent" } } } },
    "/api/health": {
      "get": {
        "summary": "Liveness (+?deep=1 per-service probe)",
        "parameters": [{ "name": "deep", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "{ status:'ok', commit }" }, "503": { "description": "degraded" } }
      }
    },
    "/api/metrics": { "get": { "summary": "Prometheus-format counters", "responses": { "200": { "description": "text/plain exposition" } } } },
    "/feed.xml": { "get": { "summary": "Atom feed of the 50 newest live listings", "responses": { "200": { "description": "application/atom+xml" } } } },
    "/sitemap.xml": { "get": { "summary": "XML sitemap", "responses": { "200": { "description": "application/xml" } } } },
    "/embed/{id}": {
      "get": {
        "summary": "Embeddable listing card (iframe)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "minimal HTML card" }, "404": { "description": "unknown listing" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Offer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "city": { "type": "string" },
          "area": { "type": "string" },
          "category": { "type": "string" },
          "type": { "type": "string" },
          "price": { "type": "integer", "description": "PHP asking price" },
          "beds": { "type": "integer" },
          "baths": { "type": "integer" },
          "sqm": { "type": "integer" },
          "amenities": { "type": "array", "items": { "type": "string" } },
          "paymentOptions": { "type": "array", "items": { "type": "string" } },
          "developer": { "type": "string" },
          "negotiable": { "type": "boolean" },
          "urgentSale": { "type": "boolean" }
        }
      }
    }
  }
}