{
  "openapi": "3.0.3",
  "info": {
    "title": "ELEARTH 3D Virtual Real Estate Marketplace API",
    "description": "Public machine-readable API specification for AI agents and developers to query 3D virtual buildings, pricing tiers, city metrics, and digital property ownership records on ELEARTH.",
    "version": "1.0.0",
    "contact": {
      "name": "ELEARTH Developer & AI Ecosystem",
      "url": "https://docs.elearth.com/marketplace/marketplace",
      "email": "support@elearth.com"
    }
  },
  "servers": [
    {
      "url": "https://elearth.com",
      "description": "Production ELEARTH API Gateway"
    },
    {
      "url": "https://docs.elearth.com",
      "description": "ELEARTH Documentation & Spec Mirror"
    }
  ],
  "paths": {
    "/api/marketplace/cities": {
      "get": {
        "summary": "List all active 3D cities in the ELEARTH marketplace",
        "description": "Returns verified real-world metropolitan hubs currently live on ELEARTH with coordinates, base property prices, and active 3D buildings.",
        "operationId": "getMarketplaceCities",
        "responses": {
          "200": {
            "description": "Successful retrieval of active cities list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitiesListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/buildings/owned": {
      "get": {
        "summary": "Query owned virtual buildings and titles",
        "description": "Returns verified list of sovereign virtual properties currently held by platform users, including building ID, city, tier, and timestamp.",
        "operationId": "getOwnedBuildings",
        "responses": {
          "200": {
            "description": "Successful retrieval of owned building registry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnedBuildingsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/marketplace/tiers": {
      "get": {
        "summary": "Get building pricing tiers and classification guidelines",
        "description": "Returns the 7 primary price tiers (from Standard to Wonder / Iconic), USD valuations, El-Coin equivalents, and height thresholds.",
        "operationId": "getPriceTiers",
        "responses": {
          "200": {
            "description": "Price tiers definition and valuation rules",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceTiersResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CitiesListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "count": { "type": "integer", "example": 100 },
          "cities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "example": "dubai" },
                "name": { "type": "string", "example": "دبي" },
                "nameEn": { "type": "string", "example": "Dubai" },
                "lat": { "type": "number", "example": 25.2048 },
                "lon": { "type": "number", "example": 55.2708 },
                "basePriceUsd": { "type": "number", "example": 5 }
              }
            }
          }
        }
      },
      "OwnedBuildingsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "count": { "type": "integer", "example": 1420 },
          "buildings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "buildingId": { "type": "string", "example": "b_dubai_burj_khalifa_01" },
                "city": { "type": "string", "example": "dubai" },
                "tier": { "type": "string", "example": "iconic" },
                "ownerHandle": { "type": "string", "example": "VirtualTycoon" }
              }
            }
          }
        }
      },
      "PriceTiersResponse": {
        "type": "object",
        "properties": {
          "tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "example": "tier_1" },
                "label": { "type": "string", "example": "Standard Residential" },
                "priceUsd": { "type": "number", "example": 5 },
                "priceCoins": { "type": "number", "example": 500 }
              }
            }
          }
        }
      }
    }
  }
}