{
  "openapi": "3.0.0",
  "info": {
    "title": "See It Here First Property Search API",
    "version": "1.0.0",
    "description": "Public read-only API for searching exclusive pre-market property listings across the UK. Fully compatible with AI agents, ChatGPT plugins, and automated property discovery. No authentication required. Find properties before they hit the market.",
    "contact": {
      "name": "See It Here First",
      "url": "https://seeitherefirst.co.uk"
    }
  },
  "servers": [
    {
      "url": "https://prod-api.seeitherefirst.co.uk",
      "description": "Production API"
    },
    {
      "url": "https://dev-api.seeitherefirst.co.uk",
      "description": "Development API"
    }
  ],
  "tags": [
    {
      "name": "search",
      "description": "Property search operations"
    },
    {
      "name": "properties",
      "description": "Property feed operations"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "tags": ["search"],
        "summary": "Search properties",
        "description": "Search properties with filters for bedrooms, location, and market status. Returns paginated results suitable for AI processing.",
        "operationId": "searchProperties",
        "parameters": [
          {
            "name": "min_beds",
            "in": "query",
            "description": "Minimum number of bedrooms",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "example": 3
          },
          {
            "name": "max_beds",
            "in": "query",
            "description": "Maximum number of bedrooms (optional upper bound)",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 3
          },
          {
            "name": "postcode",
            "in": "query",
            "description": "Root or partial postcode",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "CV12"
          },
          {
            "name": "off_market_only",
            "in": "query",
            "description": "Filter for off-market exclusives only",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "example": true
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "example": 10
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": 20184,
                      "address": "42 Church Street, Bedworth",
                      "postcode": "CV12 8LX",
                      "price": 285000,
                      "bedrooms": 3,
                      "off_market": true,
                      "agent": "Sheldon Bosley Knight",
                      "image": "https://cdn.seeitherefirst.co.uk/images/20184_1.jpg",
                      "url": "https://seeitherefirst.co.uk/properties/20184"
                    }
                  ],
                  "meta": {
                    "total": 6,
                    "page": 1,
                    "pages": 1
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "public, max-age=3600"
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties": {
      "get": {
        "tags": ["properties"],
        "summary": "Get properties feed",
        "description": "Get properties feed with advanced filtering options",
        "operationId": "getProperties",
        "parameters": [
          {
            "name": "skip",
            "in": "query",
            "description": "Skip N results",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "take",
            "in": "query",
            "description": "Number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "description": "Minimum price",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "description": "Maximum price",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "minBeds",
            "in": "query",
            "description": "Minimum bedrooms",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "maxBeds",
            "in": "query",
            "description": "Maximum bedrooms",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offMarketOnly",
            "in": "query",
            "description": "Off-market properties only",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["newest", "oldest", "price_desc", "price_asc"],
              "default": "newest"
            }
          },
          {
            "name": "withImagesOnly",
            "in": "query",
            "description": "Only include properties with images",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertiesResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Property": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Property ID"
          },
          "address": {
            "type": "string",
            "description": "Full property address"
          },
          "postcode": {
            "type": "string",
            "description": "Property postcode"
          },
          "price": {
            "type": "integer",
            "nullable": true,
            "description": "Property price in pounds"
          },
          "bedrooms": {
            "type": "integer",
            "description": "Number of bedrooms"
          },
          "off_market": {
            "type": "boolean",
            "description": "Whether the property is off-market"
          },
          "agent": {
            "type": "string",
            "description": "Agent name"
          },
          "image": {
            "type": "string",
            "nullable": true,
            "description": "URL to property image"
          },
          "url": {
            "type": "string",
            "description": "URL to property page"
          }
        },
        "required": ["id", "address", "postcode", "bedrooms", "off_market", "agent", "url"]
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Property"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["data", "meta"]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of results"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "pages": {
            "type": "integer",
            "description": "Total number of pages"
          }
        },
        "required": ["total", "page", "pages"]
      },
      "PropertiesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "description": "Array of property objects"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of results"
          },
          "total_count": {
            "type": "integer",
            "description": "Total number of results (alternate field)"
          }
        }
      }
    },
    "securitySchemes": {
      "public": {
        "type": "apiKey",
        "in": "query",
        "name": "No authentication required",
        "description": "This API is public and does not require authentication"
      }
    }
  }
}