{"openapi":"3.0.3","info":{"title":"KARAKTER Realty Agent API","version":"1.2.0","description":"Public, read-only-plus-lead-capture API for AI agents and developers. Live Calgary real estate listings, neighbourhood and market statistics, calculators, and a consultation-booking endpoint that funnels into KARAKTER's CRM.","contact":{"name":"Ryan Van Spengen, KARAKTER Realty","email":"ryan@karakterrealty.com","url":"https://www.karakterrealty.com/"}},"servers":[{"url":"https://www.karakterrealty.com/api/v1","description":"Production"}],"paths":{"/listings":{"get":{"summary":"Search live Calgary MLS listings","operationId":"searchListings","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text match on address, community, city, MLS number."},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"community","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"},"description":"Detached, Semi-Detached, Townhouse, Condo, etc."},{"name":"bedsMin","in":"query","schema":{"type":"integer","minimum":0}},{"name":"bathsMin","in":"query","schema":{"type":"integer","minimum":0}},{"name":"priceMin","in":"query","schema":{"type":"integer","minimum":0}},{"name":"priceMax","in":"query","schema":{"type":"integer","minimum":0}},{"name":"sqftMin","in":"query","schema":{"type":"integer","minimum":0},"description":"Minimum above-grade square footage."},{"name":"sqftMax","in":"query","schema":{"type":"integer","minimum":0},"description":"Maximum above-grade square footage (listings with unreported area are excluded)."},{"name":"yearBuiltMin","in":"query","schema":{"type":"integer"},"description":"Built in this year or later."},{"name":"yearBuiltMax","in":"query","schema":{"type":"integer"},"description":"Built in this year or earlier."},{"name":"maxDom","in":"query","schema":{"type":"integer","minimum":1},"description":"Max days on market — 1 = listed today, 7 = new this week."},{"name":"garage","in":"query","schema":{"type":"boolean"},"description":"Only listings with a garage. Underground and parkade parking count (a condo's garage); a surface stall does not."},{"name":"keywords","in":"query","schema":{"type":"string"},"description":"Comma-separated feature keywords matched against the listing description, e.g. \"pool, walkout basement\". Spelling variants match (\"walk-out\" = \"walkout\"), \"den\" also finds an office or flex room, and a term outside the built-in vocabulary matches when all of its words appear in the listing."},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price","priceDesc","beds"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Matching listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearchResult"}}}},"503":{"description":"Listing data temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/search":{"get":{"summary":"Natural-language listing search","operationId":"searchListingsNatural","description":"Parse a plain-English query into filters and search. Understands beds, baths, price, type, neighbourhood, square footage, year built, listing freshness (\"new this week\"), garage, and feature keywords. Returns the interpreted filters and parse source alongside results.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"e.g. \"4 bed detached in Aspen Woods under 1.5M with a garage, built after 2015\""},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price","priceDesc","beds"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Results + interpreted filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearchResult"}}}}}}},"/listings/{id}":{"get":{"summary":"Get one listing by id","operationId":"getListing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The listing.","content":{"application/json":{"schema":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/Listing"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facets":{"get":{"summary":"Available filter facets (cities, communities, price range)","operationId":"getFacets","responses":{"200":{"description":"Facets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facets"}}}}}}},"/neighbourhoods/{community}/stats":{"get":{"summary":"Aggregate market stats for a community","operationId":"getNeighbourhoodStats","parameters":[{"name":"community","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeighbourhoodStats"}}}}}}},"/market-stats":{"get":{"summary":"Calgary market dashboard data","operationId":"getMarketStats","responses":{"200":{"description":"Market stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketStats"}}}}}}},"/calculators":{"get":{"summary":"Catalogue of Calgary real estate calculators","operationId":"listCalculators","responses":{"200":{"description":"Calculators.","content":{"application/json":{"schema":{"type":"object","properties":{"calculators":{"type":"array","items":{"$ref":"#/components/schemas/Calculator"}}}}}}}}}},"/leads":{"post":{"summary":"Submit a consultation / information request (creates a CRM lead)","operationId":"createLead","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRequest"}}}},"responses":{"201":{"description":"Lead captured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResponse"}}}},"400":{"description":"Validation error (missing/invalid email or consent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited."}}}},"/health":{"get":{"summary":"API + listing-source health","operationId":"getHealth","responses":{"200":{"description":"OK."}}}},"/openapi.json":{"get":{"summary":"This OpenAPI document","operationId":"getOpenApi","responses":{"200":{"description":"OpenAPI 3 spec."}}}}},"components":{"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"string"},"mlsNumber":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"community":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"province":{"type":"string","nullable":true},"price":{"type":"integer","nullable":true},"type":{"type":"string","nullable":true},"beds":{"type":"integer","nullable":true},"baths":{"type":"integer","nullable":true},"daysOnMarket":{"type":"integer","nullable":true},"photo":{"type":"string","nullable":true},"sqft":{"type":"integer","nullable":true},"yearBuilt":{"type":"integer","nullable":true},"description":{"type":"string","nullable":true}},"required":["id"]},"ListingSearchResult":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"fetchedAt":{"type":"integer"},"source":{"type":"string","enum":["store","cache","ddf","fallback"]},"warnings":{"type":"array","items":{"type":"string"},"description":"Present when input had to be truncated to fit the filter contract (e.g. keyword terms beyond the cap were dropped) — the search ran narrower than requested."},"interpretedFilters":{"type":"object","description":"Natural-language search only: the structured filters parsed from the query."},"usedLlm":{"type":"boolean","description":"Natural-language search only: whether an LLM contributed to the parse."},"parseSource":{"type":"string","enum":["llm","merged","heuristic","freetext"],"description":"Natural-language search only: which parser layer(s) produced the filters."},"closest":{"type":"object","description":"Present only when `total` is 0 and the search asked for two or more features (garage and/or keywords). Listings that pass every other filter and have at least one of the features, most features first (up to 24). Each listing carries `match.has` and `match.missing`. A Condo search also ranks townhouses that pay condo fees, flagged `match.condoTownhouse`.","properties":{"criteria":{"type":"array","items":{"type":"string"},"description":"The requested features, e.g. [\"garage\", \"den\", \"walkout basement\"]."},"total":{"type":"integer","description":"How many listings have at least one of the features."},"condoTownhouses":{"type":"integer","description":"Condo searches only: how many of those are townhouses that pay condo fees. Omitted when none."},"listings":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Listing"},{"type":"object","properties":{"match":{"type":"object","properties":{"has":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}},"condoTownhouse":{"type":"boolean","description":"A townhouse that pays condo fees, included in a Condo search."}}}}}]}}}}}},"Facets":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"communities":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"priceRange":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}},"NeighbourhoodStats":{"type":"object","properties":{"community":{"type":"string"},"count":{"type":"integer"},"avgPrice":{"type":"integer"},"medianPrice":{"type":"integer"},"minPrice":{"type":"integer"},"maxPrice":{"type":"integer"},"avgDom":{"type":"integer"},"avgHours":{"type":"integer"},"typeCounts":{"type":"object","additionalProperties":{"type":"integer"}},"bedCounts":{"type":"object","additionalProperties":{"type":"integer"}},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"fetchedAt":{"type":"integer"}}},"MarketStats":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"data":{"type":"object","nullable":true}}},"Calculator":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"}}},"LeadRequest":{"type":"object","required":["name","email","consentToContact"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"message":{"type":"string","description":"What the prospect wants help with."},"inquiryType":{"type":"string","description":"e.g. buying, selling, downsizing, upsizing, estate, general."},"consentToContact":{"type":"boolean","description":"Must be true — the prospect consents to be contacted."},"sourcePage":{"type":"string"}}},"LeadResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}