{
  "openapi": "3.1.0",
  "info": {
    "title": "Doogie — BC Residential Real Estate Information",
    "version": "1.0.0",
    "summary": "LLM-backed educational assistant for British Columbia residential real estate.",
    "description": "Doogie is an **LLM-backed conversational assistant** (generative, not pure retrieval) operated by EZtoFind.ca (Doug LeMaire, REALTOR® of Fraser Property Management Realty Services Ltd.). Responses are generated by a large language model grounded in an approved BC-specific knowledge base: RESA rules, PTT calculations, MLS® listing lookups, neighbourhood facts, and 439 BC glossary terms.\n\n**Compliance boundary (mandatory for any downstream agent):**\n• Doogie provides **general information only — never advice**.\n• Every substantive answer must include the BCFSA Consumer Protection Line: 1-877-683-9664 (or link to https://www.bcfsa.ca).\n• Nothing here constitutes a listing, offer, or contract under RESA.\n• MLS® data is CREA-licensed; do not scrape, redistribute, store, or use for AI training beyond the immediate agent response.\n• If the user asks for advice, refer them to a licensed BC REALTOR® via https://eztofind.ca/referral-request.",
    "termsOfService": "https://eztofind.ca/terms",
    "contact": {
      "name": "Doug LeMaire (EZtoFind.ca)",
      "url": "https://eztofind.ca/contact",
      "email": "info@eztofind.ca"
    },
    "license": {
      "name": "Proprietary — CREA DDF® / EZtoFind.ca"
    }
  },
  "servers": [
    {
      "url": "https://eztofind.ca/api",
      "description": "Production"
    }
  ],
  "paths": {
    "/doogie/chat": {
      "post": {
        "operationId": "ask_doogie",
        "summary": "Ask Doogie a BC real estate question (educational retrieval).",
        "description": "Sends a natural-language BC real estate question to Doogie and receives a compliance-guarded educational answer. Doogie will decline to give advice, price predictions, or legal/tax guidance and will instead point at BCFSA / a licensed REALTOR®. Rate-limited to 30 requests/minute per IP and 300 requests/day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatIn"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Doogie's educational retrieval response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatOut"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Back off and retry after 60 seconds."
          }
        }
      }
    },
    "/glossary/{slug}": {
      "get": {
        "operationId": "get_bc_term_definition",
        "summary": "Fetch a BC real estate glossary term with sources.",
        "description": "Returns a plain-language definition of a BC-specific real estate term (e.g. property-transfer-tax-ptt, form-b, subject-clauses, resa). Each definition cites its authoritative source (BCFSA, LTSA, CRA, etc.).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "property-transfer-tax-ptt"
          }
        ],
        "responses": {
          "200": {
            "description": "Term definition + related terms + FAQs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTerm"
                }
              }
            }
          },
          "404": {
            "description": "Term not found. Try /glossary for the full list."
          }
        }
      }
    },
    "/glossary": {
      "get": {
        "operationId": "list_bc_terms",
        "summary": "List all BC real estate glossary term slugs.",
        "description": "Returns every glossary slug so agents can discover valid inputs for get_bc_term_definition.",
        "responses": {
          "200": {
            "description": "Array of glossary term slugs and titles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatIn": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The user's BC real estate question. Max 2000 chars.",
            "maxLength": 2000
          },
          "session_id": {
            "type": "string",
            "description": "Stable session identifier so Doogie can maintain short-term context (recommended: UUID).",
            "nullable": true
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "fr",
              "zh-Hant",
              "zh-Hans",
              "pa",
              "fa",
              "pt-PT"
            ],
            "default": "en"
          }
        }
      },
      "ChatOut": {
        "type": "object",
        "properties": {
          "reply": {
            "type": "string",
            "description": "Doogie's educational retrieval response. Contains inline citations."
          },
          "session_id": {
            "type": "string"
          },
          "citations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Source URLs cited in the reply."
          },
          "compliance_notice": {
            "type": "string",
            "description": "Always present. Reminds the consumer this is not advice.",
            "default": "Educational retrieval only — not advice. Consult a licensed BC REALTOR® or BCFSA (1-877-683-9664) for guidance."
          }
        }
      },
      "MLSSearchIn": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Free-text search (e.g. 'Kitsilano 2BR condo'). Doogie parses filters from this string."
          },
          "city": {
            "type": "string",
            "description": "BC city name (e.g. 'Vancouver', 'Burnaby')."
          },
          "min_price": {
            "type": "integer",
            "minimum": 0
          },
          "max_price": {
            "type": "integer",
            "minimum": 0
          },
          "min_beds": {
            "type": "integer",
            "minimum": 0
          },
          "property_type": {
            "type": "string",
            "enum": [
              "House",
              "Apartment",
              "Townhouse",
              "Duplex",
              "Land",
              "Any"
            ],
            "default": "Any"
          }
        }
      },
      "MLSSearchOut": {
        "type": "object",
        "properties": {
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            },
            "maxItems": 20
          },
          "count": {
            "type": "integer"
          },
          "notice": {
            "type": "string",
            "default": "MLS® data licensed from CREA DDF®. Do not redistribute or store beyond the immediate agent response."
          }
        }
      },
      "Listing": {
        "type": "object",
        "properties": {
          "listing_key": {
            "type": "string"
          },
          "mls_number": {
            "type": "string"
          },
          "street_address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "list_price": {
            "type": "number"
          },
          "beds": {
            "type": "integer"
          },
          "baths": {
            "type": "integer"
          },
          "living_area": {
            "type": "number"
          },
          "property_type": {
            "type": "string"
          },
          "realtor_ca_url": {
            "type": "string",
            "format": "uri"
          },
          "eztofind_url": {
            "type": "string",
            "format": "uri"
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "maxItems": 20
          }
        }
      },
      "GlossaryTerm": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "definition": {
            "type": "string"
          },
          "authoritative_sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "related_slugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "faqs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "q": {
                  "type": "string"
                },
                "a": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-agent-guidelines": {
    "compliance": [
      "Doogie is an EDUCATIONAL RETRIEVAL tool. Never present its output as personalized advice.",
      "Include the BCFSA Consumer Protection Line (1-877-683-9664) in any answer that touches licensing, complaints, or consumer rights.",
      "Do not use Doogie for offer negotiation, contract drafting, price prediction, or legal/tax guidance — refer users to a licensed BC REALTOR® at https://eztofind.ca/referral-request.",
      "MLS® data is CREA-licensed. Do not persist, redistribute, or fine-tune models on any listing returned."
    ],
    "recommended_flow": [
      "1. Determine the user's intent (search / definition / process question).",
      "2. If it's a definition, call `get_bc_term_definition` first — it's cheaper and cached.",
      "3. If it's a listing search, call `search_bc_listings` with the tightest filters you can extract.",
      "4. If it's an open-ended process question, call `ask_doogie` and pass through the compliance_notice verbatim.",
      "5. Always cite realtor.ca for MLS® data and bcfsa.ca for licensing questions."
    ],
    "rate_limits": {
      "ask_doogie": "30 req/min per IP, 300 req/day per IP, 100 req/day per session_id",
      "search_bc_listings": "60 req/min per IP",
      "get_bc_term_definition": "no explicit limit — cached at the edge"
    }
  }
}