{
  "openapi": "3.0.3",
  "info": {
    "title": "AIListKit AI Listing Factory API",
    "description": "Programmatic Real Estate Listing Generator, Fair Housing Compliance Auditor, and MLS Package Factory for AI Agents and Brokerage Automations.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://ailistkit.com/api/v1",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/factory/ingest": {
      "post": {
        "operationId": "ingestPropertyData",
        "summary": "Ingest and normalize raw property specs, tax parcel info, and architectural features.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "parcel_id": { "type": "string" },
                  "address": { "type": "string" },
                  "city": { "type": "string" },
                  "county": { "type": "string" },
                  "raw_specs": {
                    "type": "object",
                    "properties": {
                      "bedrooms": { "type": "number" },
                      "bathrooms": { "type": "number" },
                      "sqft": { "type": "number" },
                      "list_price": { "type": "number" }
                    },
                    "required": ["bedrooms", "bathrooms", "sqft", "list_price"]
                  }
                },
                "required": ["address", "city", "raw_specs"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Normalized property profile" },
          "400": { "description": "Missing or invalid property data" },
          "401": { "description": "Unauthorized - Missing or invalid API key" }
        }
      }
    },
    "/factory/mls-package": {
      "post": {
        "operationId": "generateMlsListingPackage",
        "summary": "Generate complete Fair Housing compliant MLS copy, private remarks, and social marketing package.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "property_profile": {
                    "type": "object",
                    "properties": {
                      "address": { "type": "string" },
                      "city": { "type": "string" },
                      "bedrooms": { "type": "number" },
                      "bathrooms": { "type": "number" },
                      "sqft": { "type": "number" },
                      "list_price": { "type": "number" }
                    },
                    "required": ["address", "city", "bedrooms", "bathrooms", "sqft", "list_price"]
                  },
                  "tone": { "type": "string", "enum": ["Luxury", "Investor", "Fast-Sale", "Classic"] },
                  "mls_char_limit": { "type": "integer" }
                },
                "required": ["property_profile"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "MLS listing package with character-counted remarks" },
          "400": { "description": "Invalid input payload" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/factory/audit-fair-housing": {
      "post": {
        "operationId": "auditFairHousingCompliance",
        "summary": "Scan real estate copy for Federal and Florida Fair Housing protected class violations.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "listing_text": { "type": "string" }
                },
                "required": ["listing_text"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Fair Housing audit report with risk score and remediations" },
          "400": { "description": "Listing text required" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/factory/photo-staging-brief": {
      "post": {
        "operationId": "generatePhotoStagingBrief",
        "summary": "Generate photography shot lists and virtual staging prompts by room and architectural style.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "room_list": { "type": "array", "items": { "type": "string" } },
                  "architectural_style": { "type": "string" }
                },
                "required": ["room_list"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Shot list and staging brief with virtual staging disclosure" },
          "400": { "description": "Room list required" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/factory/instant-generate": {
      "post": {
        "operationId": "instantGenerateListing",
        "summary": "All-in-one generator for interactive playgrounds: insets, audits, builds MLS package, and generates photo brief in 1 call.",
        "security": [
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": { "type": "string" },
                  "city": { "type": "string" },
                  "raw_specs": {
                    "type": "object",
                    "properties": {
                      "bedrooms": { "type": "number" },
                      "bathrooms": { "type": "number" },
                      "sqft": { "type": "number" },
                      "list_price": { "type": "number" }
                    },
                    "required": ["bedrooms", "bathrooms", "sqft", "list_price"]
                  },
                  "tone": { "type": "string" }
                },
                "required": ["address", "city", "raw_specs"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Complete instant listing package" },
          "400": { "description": "Missing required property data" },
          "401": { "description": "Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Header-only API Key authentication"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT bearer token authorization"
      }
    }
  }
}