{
  "openapi": "3.1.0",
  "info": {
    "title": "AddressIntel B2B API",
    "description": "Algorithmic Deal Sourcing for Luxury Spec Builders and AI Agents. Access proprietary real estate intelligence, teardown probabilities, and market heat metrics.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://addressintel.co/api",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/market-signals": {
      "get": {
        "summary": "List Market Signals",
        "description": "Retrieves top investment opportunities scored by our proprietary engine. Properties are scored on teardown potential, flippability, and more.",
        "operationId": "listMarketSignals",
        "parameters": [
          {
            "name": "market",
            "in": "query",
            "description": "Filter by market ('sf-peninsula' or 'nantucket'). Defaults to 'sf-peninsula'.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Filter by city name (e.g., 'Atherton')",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "query",
            "description": "Search for a specific address",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size. Capped to your plan's maximum (demo 5, free 25, pro 500).",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip for pagination.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response containing a list of scored properties.",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "count": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/PropertySignal" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" },
                    "asOf": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the returned data was current."
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/properties/{id}": {
      "get": {
        "summary": "Get Property Intelligence",
        "description": "Retrieves detailed intelligence for a single property, including aggregated comp data and proprietary scores. (Free Tier)",
        "operationId": "getPropertyIntelligence",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier of the property",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response containing property details and intelligence.",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "$ref": "#/components/schemas/PropertyDetail" },
                    "asOf": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": {
            "description": "Property not found.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/keys": {
      "post": {
        "summary": "Create a Free API Key",
        "description": "Self-serve issuance of a free-tier API key. Limited to 5 keys per day per IP.",
        "operationId": "createKey",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": { "email": { "type": "string", "format": "email" } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A new free-tier API key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "key": { "type": "string", "example": "sk_free_..." },
                    "tier": { "type": "string", "example": "free" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/subscribe": {
      "post": {
        "summary": "Subscribe to Market Briefings",
        "description": "Add an email to a market's newsletter list.",
        "operationId": "subscribe",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "source": { "type": "string" },
                  "market": { "type": "string", "example": "sf-peninsula" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscribed.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/webhooks/register": {
      "post": {
        "summary": "Register a Webhook (Pro)",
        "description": "Register an HTTPS endpoint to receive real-time events. Requires a Pro API key. Returns a per-endpoint signingSecret used to verify the X-AddressIntel-Signature header.",
        "operationId": "registerWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint." },
                  "events": {
                    "type": "array",
                    "items": { "type": "string", "enum": ["permit.created", "property.score_updated"] }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook registered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "registeredUrl": { "type": "string" },
                    "events": { "type": "array", "items": { "type": "string" } },
                    "signingSecret": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": {
            "description": "Webhooks require a Pro plan.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Requests allowed per minute for your plan.",
        "schema": { "type": "integer" }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests remaining in the current window.",
        "schema": { "type": "integer" }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "BadRequest": {
        "description": "Invalid request.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "headers": {
          "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
          "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string", "description": "Human-readable message." },
          "code": {
            "type": "string",
            "enum": ["unauthorized", "forbidden", "rate_limited", "not_found", "bad_request", "internal_error"]
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "total": { "type": "integer" },
          "returned": { "type": "integer" },
          "nextOffset": { "type": "integer", "nullable": true }
        }
      },
      "PropertySignal": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "teardownScore": {
            "type": "number",
            "description": "0-100 probability that the property is a teardown."
          },
          "flippabilityScore": {
            "type": "number",
            "description": "0-100 score indicating renovation potential."
          },
          "developerROI": {
            "type": "number",
            "description": "Estimated Return on Investment percentage for developers."
          },
          "metadata": {
            "type": "object",
            "properties": {
              "sqft": {
                "type": "number"
              },
              "lotSize": {
                "type": "number"
              },
              "daysOnMarket": {
                "type": "number"
              }
            }
          }
        }
      },
      "PropertyDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "intelligence": {
            "type": "object",
            "properties": {
              "teardownScore": {
                "type": "number"
              },
              "flippabilityScore": {
                "type": "number"
              },
              "marketHeatIndex": {
                "type": "number"
              },
              "biddingWarPredictor": {
                "type": "number"
              }
            }
          },
          "comparables": {
            "type": "object",
            "properties": {
              "recentSalesCount": {
                "type": "integer"
              },
              "avgPricePerSqft": {
                "type": "number"
              }
            }
          }
        }
      }
    }
  }
}