{
  "openapi": "3.1.0",
  "info": {
    "title": "Royal Properties AI Agent Gateway",
    "version": "0.3.1",
    "description": "Read-only published real estate listings; rate limit 20 requests per server IP per UTC hour and 300 per site UTC day (best effort). No pagination. No mutations."
  },
  "servers": [
    {
      "url": "https://royalpropertybg.com"
    }
  ],
  "paths": {
    "/wp-json/royal-properties-agent/v1/properties": {
      "get": {
        "operationId": "searchRoyalProperties",
        "summary": "Find recent published listings",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Term name or slug from property_city"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Term name or slug from property_category"
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Term name or slug from property_action_category"
          },
          {
            "name": "feature",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Term name or slug from property_features"
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Inclusive numeric price bound"
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Inclusive numeric price bound"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listings or empty result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "const": "Royal Properties"
                    },
                    "read_only": {
                      "const": true
                    },
                    "currency": {
                      "type": "string",
                      "enum": [
                        "EUR",
                        "not_verified"
                      ]
                    },
                    "count": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 10,
                      "description": "Returned item count, not total inventory"
                    },
                    "items": {
                      "type": "array",
                      "maxItems": 10,
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "price_value": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "size_sqm": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "image_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "city": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "type": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "transaction": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "features": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "agent": {
                            "anyOf": [
                              {
                                "type": "null"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "url": {
                                    "type": "string",
                                    "format": "uri"
                                  }
                                },
                                "required": [
                                  "name",
                                  "url"
                                ]
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "title",
                          "url",
                          "price_value",
                          "size_sqm",
                          "image_url",
                          "city",
                          "type",
                          "transaction",
                          "features",
                          "agent"
                        ]
                      }
                    }
                  },
                  "required": [
                    "source",
                    "read_only",
                    "currency",
                    "count",
                    "items"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid filter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Access disabled or route unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Catalog unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}