{"openapi":"3.1.0","info":{"title":"Halloween.chat Public API","version":"1.0.0","summary":"Deterministic zero-token edge directory API for Halloween.chat.","description":"High-performance verified directory API for Halloween.chat (halloween.chat). Provides fast, deterministic read endpoints for places, cities, categories, search suggestions, and merchant claims with zero runtime token spend."},"paths":{"/api/v1/posts":{"get":{"operationId":"getPosts","summary":"Published articles for this host","parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string"}}],"description":"Hountix includes eligible published MCP posts. Drafts, invalid metadata and future publication dates are omitted. Homepage promotion dates do not expire the article.","responses":{"200":{"description":"Published posts","content":{"application/json":{"example":{"posts":[{"slug":"lady-gaga-queen-of-halloween","brandId":"haunt","title":"Lady Gaga, Queen of Halloween","summary":"Hountix makes its editorial case for a Halloween crown.","date":"2026-10-29","author":"Hountix","language":"en","bodyMarkdown":"An original culture article with source links.","readingTimeMinutes":1}]},"schema":{"type":"object","required":["posts"],"properties":{"posts":{"type":"array","items":{"type":"object","required":["slug","brandId","title","summary","date","author","language","bodyMarkdown"],"properties":{"slug":{"type":"string"},"brandId":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"date":{"type":"string","format":"date"},"author":{"type":"string"},"language":{"type":"string"},"country":{"type":"string"},"bodyMarkdown":{"type":"string"},"readingTimeMinutes":{"type":"integer","minimum":1},"homepageFeature":{"type":"object","additionalProperties":false,"required":["eyebrow","ctaLabel","startsOn","endsOn","entries"],"properties":{"eyebrow":{"type":"string"},"ctaLabel":{"type":"string"},"startsOn":{"type":"string","format":"date","description":"Inclusive date in America/New_York"},"endsOn":{"type":"string","format":"date","description":"Inclusive date in America/New_York"},"entries":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","additionalProperties":false,"required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"}}}}}},"applies_to":{"type":"array","items":{"type":"string"}},"applies_to_mode":{"type":"string","enum":["only","all_except","global"]},"excluded_regions":{"type":"array","items":{"type":"string"}},"primary_region":{"type":"string"},"about_places":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"jurisdiction_authority":{"type":"string"},"region_notes":{"type":"string"},"alternative_urls":{"type":"object","additionalProperties":{"type":"string"}},"visibility_closure":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v1/posts/{slug}":{"get":{"operationId":"getPost","summary":"One published article for this host","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published post","content":{"application/json":{"schema":{"type":"object","required":["slug","brandId","title","summary","date","author","language","bodyMarkdown"],"properties":{"slug":{"type":"string"},"brandId":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"date":{"type":"string","format":"date"},"author":{"type":"string"},"language":{"type":"string"},"country":{"type":"string"},"bodyMarkdown":{"type":"string"},"readingTimeMinutes":{"type":"integer","minimum":1},"homepageFeature":{"type":"object","additionalProperties":false,"required":["eyebrow","ctaLabel","startsOn","endsOn","entries"],"properties":{"eyebrow":{"type":"string"},"ctaLabel":{"type":"string"},"startsOn":{"type":"string","format":"date","description":"Inclusive date in America/New_York"},"endsOn":{"type":"string","format":"date","description":"Inclusive date in America/New_York"},"entries":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","additionalProperties":false,"required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"}}}}}},"applies_to":{"type":"array","items":{"type":"string"}},"applies_to_mode":{"type":"string","enum":["only","all_except","global"]},"excluded_regions":{"type":"array","items":{"type":"string"}},"primary_region":{"type":"string"},"about_places":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"jurisdiction_authority":{"type":"string"},"region_notes":{"type":"string"},"alternative_urls":{"type":"object","additionalProperties":{"type":"string"}},"visibility_closure":{"type":"array","items":{"type":"string"}}}},"example":{"slug":"lady-gaga-queen-of-halloween","brandId":"haunt","title":"Lady Gaga, Queen of Halloween","summary":"Hountix makes its editorial case for a Halloween crown.","date":"2026-10-29","author":"Hountix","language":"en","bodyMarkdown":"An original culture article with source links.","readingTimeMinutes":1}}}},"404":{"description":"Missing, draft, invalid, future-dated, or another host/language"}}}},"/api/v1/guides":{"get":{"operationId":"listGuides","description":"Published Sociable Pet preparation guides. Optional country filters by exact lowercase country prefix. Sources, check date, cityId, sections and canonical records (id and display label) are the same data used by HTML. Guides do not rank or restrict directory eligibility. Other products return 404.","parameters":[{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Published guides","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["slug","country","cityId","title","language","checkedOn","summary","sections"],"properties":{"slug":{"type":"string"},"country":{"type":"string"},"cityId":{"type":"string"},"title":{"type":"string"},"language":{"type":"string","const":"en"},"checkedOn":{"type":"string","format":"date"},"summary":{"type":"string"},"sections":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["heading","body","sources","records"],"properties":{"heading":{"type":"string"},"body":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}}}}}},"example":{"items":[{"slug":"stamford-pet-care","country":"us","cityId":"us/ct/stamford","language":"en","title":"Preparing for grooming, boarding and training in Stamford","checkedOn":"2026-10-29","summary":"Start with the care you need in Stamford, Connecticut, then confirm the practical details. This limited source review covers four businesses and six separate credential records. It is not a ranking, a citywide business count or an availability check.","sections":[{"heading":"A grooming visit","body":"K9Petz at 264 Hope Street and Groom to Bloom at 875 Cove Road publish dog-grooming information and matching contacts. Ask about handling, coat condition, appointment length and the final quote. Groom to Bloom asks for a rabies certificate and two new-client forms, and assesses the dog before setting the price. Confirm requirements before travelling.","sources":[{"label":"K9Petz","url":"https://k9petz.com/"},{"label":"Groom to Bloom services","url":"https://www.groomtobloom.com/services"}],"records":[{"id":"ctdoag-951288","label":"K9Petz · grooming record"},{"id":"ctdoag-1627093","label":"Groom to Bloom · grooming record"}]},{"heading":"An overnight stay","body":"Room for Paws publishes its contact address at 72 Camp Avenue. Spot On publishes its Stamford contact at 184 Selleck Street; its hotel and hospital have different schedules. Ask who is present overnight, what to bring, how intake works and which pickup window applies. A boarding credential does not establish clinical services or emergency cover.","sources":[{"label":"Room for Paws contact","url":"https://www.roomforpawspetresort.com/contact/"},{"label":"Spot On Stamford information","url":"https://spotonvet.com/hospital/"}],"records":[{"id":"ctdoag-2223259","label":"Room for Paws · boarding record"},{"id":"ctdoag-1444225","label":"Spot On · boarding record"}]},{"heading":"A training conversation","body":"Room for Paws describes group sessions and individual training formats. Ask about methods, goals, instructor qualifications and the class currently offered. Its training record and the Spot On training record remain separate from their boarding credentials. A shared name and address do not create extra businesses.","sources":[{"label":"Room for Paws training","url":"https://www.roomforpawspetresort.com/services/training/"}],"records":[{"id":"ctdoag-2261328","label":"Room for Paws · training record"},{"id":"ctdoag-1444227","label":"Spot On · training record"}]},{"heading":"Read the record before choosing","body":"Connecticut business credentials describe a particular credential class. Individual veterinarian licences are not clinic listings. Walking, sitting and daycare are not inferred from a kennel licence. The full directory includes eligible records outside this reviewed sample. Fees, dates and intake remain questions for each provider. Requests here remain copyable drafts; nothing is sent.","sources":[{"label":"Connecticut source file","url":"https://data.ct.gov/Business/State-Licenses-and-Credentials/ngch-56tr"}],"records":[]}]}]}}}},"404":{"description":"Product has no published guide collection"}}}},"/api/v1/guides/{slug}":{"get":{"operationId":"getGuide","description":"A published Sociable Pet guide. Country is required to prevent cross-country fallback. Unknown slug, country or product returns 404. This is preparation content, not accreditation or delivery authorization.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published guide","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["slug","country","cityId","title","language","checkedOn","summary","sections"],"properties":{"slug":{"type":"string"},"country":{"type":"string"},"cityId":{"type":"string"},"title":{"type":"string"},"language":{"type":"string","const":"en"},"checkedOn":{"type":"string","format":"date"},"summary":{"type":"string"},"sections":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["heading","body","sources","records"],"properties":{"heading":{"type":"string"},"body":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}}},"example":{"slug":"stamford-pet-care","country":"us","cityId":"us/ct/stamford","language":"en","title":"Preparing for grooming, boarding and training in Stamford","checkedOn":"2026-10-29","summary":"Start with the care you need in Stamford, Connecticut, then confirm the practical details. This limited source review covers four businesses and six separate credential records. It is not a ranking, a citywide business count or an availability check.","sections":[{"heading":"A grooming visit","body":"K9Petz at 264 Hope Street and Groom to Bloom at 875 Cove Road publish dog-grooming information and matching contacts. Ask about handling, coat condition, appointment length and the final quote. Groom to Bloom asks for a rabies certificate and two new-client forms, and assesses the dog before setting the price. Confirm requirements before travelling.","sources":[{"label":"K9Petz","url":"https://k9petz.com/"},{"label":"Groom to Bloom services","url":"https://www.groomtobloom.com/services"}],"records":[{"id":"ctdoag-951288","label":"K9Petz · grooming record"},{"id":"ctdoag-1627093","label":"Groom to Bloom · grooming record"}]},{"heading":"An overnight stay","body":"Room for Paws publishes its contact address at 72 Camp Avenue. Spot On publishes its Stamford contact at 184 Selleck Street; its hotel and hospital have different schedules. Ask who is present overnight, what to bring, how intake works and which pickup window applies. A boarding credential does not establish clinical services or emergency cover.","sources":[{"label":"Room for Paws contact","url":"https://www.roomforpawspetresort.com/contact/"},{"label":"Spot On Stamford information","url":"https://spotonvet.com/hospital/"}],"records":[{"id":"ctdoag-2223259","label":"Room for Paws · boarding record"},{"id":"ctdoag-1444225","label":"Spot On · boarding record"}]},{"heading":"A training conversation","body":"Room for Paws describes group sessions and individual training formats. Ask about methods, goals, instructor qualifications and the class currently offered. Its training record and the Spot On training record remain separate from their boarding credentials. A shared name and address do not create extra businesses.","sources":[{"label":"Room for Paws training","url":"https://www.roomforpawspetresort.com/services/training/"}],"records":[{"id":"ctdoag-2261328","label":"Room for Paws · training record"},{"id":"ctdoag-1444227","label":"Spot On · training record"}]},{"heading":"Read the record before choosing","body":"Connecticut business credentials describe a particular credential class. Individual veterinarian licences are not clinic listings. Walking, sitting and daycare are not inferred from a kennel licence. The full directory includes eligible records outside this reviewed sample. Fees, dates and intake remain questions for each provider. Requests here remain copyable drafts; nothing is sent.","sources":[{"label":"Connecticut source file","url":"https://data.ct.gov/Business/State-Licenses-and-Credentials/ngch-56tr"}],"records":[]}]}}}},"404":{"description":"Guide not found for this product and country"}}}},"/health":{"get":{"operationId":"getHealth","responses":{"200":{"description":"Process is up","content":{"application/json":{"example":{"ok":true}}}}}}},"/api/v1":{"get":{"operationId":"getApiV1","responses":{"200":{"description":"API index","content":{"application/json":{"example":{"name":"directory","schemaVersion":null}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","responses":{"200":{"description":"This document","content":{"application/json":{"example":{"openapi":"3.1.0"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getApiV1OpenApi","summary":"Get live typed OpenAPI 3.1 schema specification","responses":{"200":{"description":"OpenAPI 3.1 JSON schema document","content":{"application/json":{"example":{"openapi":"3.1.0"}}}}}}},"/api/v1/search/semantic":{"get":{"operationId":"searchSemantic","summary":"Fast sub-5ms MinHash semantic search over listings","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Ranked semantic search results","content":{"application/json":{"example":{"ok":true,"query":"organic pet grooming","matches":[{"id":"p1","name":"Paw Spa","score":0.92,"category":"Pet Groomer"}]}}}}}}},"/api/v1/qr":{"get":{"operationId":"generateQrCode","summary":"Generate deterministic SVG QR code for verification or print","parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"integer","default":256}},{"name":"color","in":"query","schema":{"type":"string"}},{"name":"badge","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Deterministic Scalable Vector Graphic (SVG) QR code","content":{"image/svg+xml":{"example":"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\"></svg>"}}}}}},"/api/v1/claims/{id}/window-cling.svg":{"get":{"operationId":"getClaimWindowClingSvg","summary":"Generate print-ready vector SVG storefront window cling with QR verification code","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printable 600x800 Scalable Vector Graphic window cling badge","content":{"image/svg+xml":{"example":"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 600 800\"></svg>"}}},"404":{"description":"Claim record not found"}}}},"/api/v1/tours/walking-routes":{"get":{"operationId":"getWalkingRoutes","summary":"Generate localized walking route tour itinerary between proximate listings","parameters":[{"name":"city","in":"query","schema":{"type":"string"}},{"name":"maxStops","in":"query","schema":{"type":"integer","default":4}}],"responses":{"200":{"description":"Structured walking tour itinerary and GeoJSON feature collection","content":{"application/json":{"example":{"ok":true,"itinerary":{"id":"walk-austin-3stops","title":"Austin Walking Tour","totalStops":3,"stops":[]}}}}}}}},"/api/v1/security/crawler-check":{"get":{"operationId":"checkCrawlerVerification","summary":"Verify search engine crawler identity and detect spoofed or AI scrapers","parameters":[{"name":"ip","in":"query","schema":{"type":"string"}},{"name":"ua","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Crawler verification status and action verdict","content":{"application/json":{"example":{"ok":true,"ip":"66.249.66.1","verification":{"isVerifiedSearchBot":true,"isTrainingBot":false,"action":"allow"}}}}}}}},"/developers":{"get":{"operationId":"getDevelopers","responses":{"200":{"description":"HTML docs","content":{"text/html":{"example":"<h1>Developers</h1>"}}}}}},"/developers/changelog":{"get":{"operationId":"getDevelopersChangelog","responses":{"200":{"description":"HTML API changelog, newest first","content":{"text/html":{"example":"<h1>API Changelog</h1>"}}}}}},"/api/v1/pages/city":{"get":{"operationId":"getCityPageDto","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"region","in":"query","required":true,"schema":{"type":"string"}},{"name":"city","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"facet","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"City × category DTO for SEO pages with at least 3 published listings","content":{"application/json":{"example":{"ok":true,"page":{"country":"us","region":"ny","city":"new-york","cityName":"New York City","category":"plumbers","total":5,"title":"Licensed Plumbers in New York City | HomeCrafto","description":"Verified licensed plumbers in New York City.","canonicalUrl":"https://homecrafto.com/us/ny/new-york/plumbers","breadcrumbs":[{"name":"Home","url":"https://homecrafto.com/"},{"name":"United States","url":"https://homecrafto.com/us"},{"name":"New York","url":"https://homecrafto.com/us/ny"},{"name":"New York City","url":"https://homecrafto.com/us/ny/new-york"}],"items":[{"id":"plumber-101","name":"NYC Master Plumbing Co","address":"123 Broadway, New York, NY 10001","city":"New York","region":"ny","category":"plumbers","websiteUrl":"https://nycmasterplumbing.example.com","hoursOfOperation":"Mon-Fri 8:00 AM - 6:00 PM"}]}}}}},"404":{"description":"City page does not meet the index gate (minimum 3 published listings required) or does not exist","content":{"application/json":{"example":{"error":{"code":"NOT_FOUND","message":"City page does not meet the index gate or does not exist.","docs":"https://homecrafto.com/developers/errors#not-found"}}}}}}}},"/api/v1/listings":{"get":{"operationId":"listListings","responses":{"200":{"description":"Empty until a golden push","content":{"application/json":{"example":{"items":[]}}}}}}},"/api/v1/search":{"get":{"operationId":"searchListings","description":"Pet accepts city (country/region/city id), country, region, q (city or postal code), locale, scope (city collection or radius), radius (miles), category (canonical ids or localized slugs, comma-separated), emergency/openNow, sort (distance/name), page, view, limit (1–100) and offset. Explicit city context outranks inferred location; blank unscoped input has no origin. Total counts matched canonical records, not verified businesses or wider source-file records. Unsupported contacts, ratings, tags and ranking boosts are omitted; coordinatePrecision distinguishes approximate positions. HTML uses this same search service with 24 records per page. Tourism accepts scope (global, country, city), city (stable id or existing location), country, locale (en/es), keyword, category, group (eat-drink, art-culture, make, outside, after-dark), neighborhood, radius, sort, page and view. Explicit context returns context, items, total, inventoryTotal, categories (id/count), page, pages and coverage (available, unknown-city, no-coverage, empty-filter). City queries retain radius behavior; global results page within existing shards. Selections never filter directory eligibility. Legacy radius parameters retain their existing response.","responses":{"200":{"description":"Search listings by radius from a location or ZIP code","content":{"application/json":{"example":{"origin":{"zip":"06903","city":"Stamford","state":"CT","lat":41.136,"lng":-73.5711},"radiusMiles":25,"total":1,"items":[{"id":"ctdph-1390821","name":"NEW CANAAN VETERINARY HOSPITAL","category":"veterinarians","city":"New Canaan","region":"ct","address":"7 VITTI ST, New Canaan, CT 06840","distanceMiles":4.1,"websiteUrl":"https://newcanaanvet.example.com","hoursOfOperation":"Mon-Sat 8:00 AM - 7:00 PM"}],"surroundingCities":[{"city":"New Canaan","count":1,"minDistance":4.1}]}}}}}}},"/api/v1/search/autocomplete":{"get":{"operationId":"autocompleteSearch","responses":{"200":{"description":"Fast prefix suggestions for location and category search","content":{"application/json":{"example":{"query":"Pari","suggestions":[{"text":"Paris, France","city":"Paris","country":"FR"},{"text":"Pastelería Ideal","city":"Ciudad de México","country":"MX"}]}}}}}}},"/api/v1/search/suggest":{"get":{"operationId":"getSearchSuggestions","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"vertical","in":"query","required":false,"schema":{"type":"string"}},{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"schema":{"type":"number"}},{"name":"radiusKm","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Typo-tolerant trie suggestions with optional spatial proximity boost","content":{"application/json":{"example":{"query":"plumb","total":1,"hasTypoCorrection":false,"suggestions":[{"type":"category","text":"Plumbing","category":"plumbing","country":"us","url":"/us/categories/plumbing","score":100}]}}}}}}},"/api/v1/places/{id}":{"get":{"operationId":"getPlaceDto","description":"Hountix published place data, using the same city visibility gate as the website. actualCity is the reviewed venue locality; metro is the directory grouping and city retains that legacy grouping. facts contain key, value, sourceUrl and checkedOn. locations separates source-dated businessAddress, meetingPoint and serviceArea. address remains the Google business address and may be empty for service-area businesses; displayAddress prefers the sourced guest meeting point. timeZone is the recorded venue IANA zone, omitted if unknown. schedule contains sourced date/status, optional kind (attraction_hours by default, ticket_window or departure) and venue-local opens/closes. A departure has opens only. Ticket windows and departures never establish OPEN NOW or attraction closing times. priceOptions contain a named description, decimal-string amount, currency, tax treatment (additional/included/unknown), sourceUrl and checkedOn. Empty arrays mean unconfirmed, never closed or false. Unknown actualCity, contact and licence fields are omitted. Unavailable on other products.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"Published public place record; verified refers only to licence validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","place"],"properties":{"ok":{"const":true},"place":{"type":"object","additionalProperties":false,"required":["id","name","address","city","region","country","category","metro","facts","schedule","priceOptions","verified","licenseValidationStatus","canonicalUrl"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"city":{"type":"string","description":"Legacy directory grouping; use actualCity for venue locality."},"region":{"type":"string"},"country":{"type":"string"},"category":{"type":"string"},"phone":{"type":"string"},"licenseNumber":{"type":"string"},"displayAddress":{"type":"string","description":"Guest meeting-point address when sourced, otherwise the Google business address."},"locations":{"type":"object","additionalProperties":false,"properties":{"businessAddress":{"type":"object","additionalProperties":false,"required":["address","city","region","country","sourceUrl","checkedOn"],"properties":{"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"},"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"address":{"type":"string"},"instructions":{"type":"string"}}},"meetingPoint":{"type":"object","additionalProperties":false,"required":["address","city","region","country","sourceUrl","checkedOn"],"properties":{"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"},"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"address":{"type":"string"},"instructions":{"type":"string"}}},"serviceArea":{"type":"object","additionalProperties":false,"required":["label","city","region","country","sourceUrl","checkedOn"],"properties":{"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"},"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"label":{"type":"string"}}},"timeZone":{"type":"string","description":"Venue IANA time zone; omitted when not recorded."}}},"photo":{"type":"object","additionalProperties":false,"required":["url","sourceUrl","checkedOn","rights"],"properties":{"url":{"type":"string","format":"uri"},"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"},"rights":{"type":"object","additionalProperties":false,"required":["basis","sourceUrl","credit"],"properties":{"basis":{"type":"string","enum":["permission","licensed","public_domain"]},"sourceUrl":{"type":"string","format":"uri"},"credit":{"type":"string"},"licenseUrl":{"type":"string","format":"uri","description":"Required for licensed photographs."}}}}},"timeZone":{"type":"string","description":"Venue IANA zone. Absent means unknown; do not assume the country has one time zone."},"actualCity":{"type":"string","description":"Reviewed venue locality, omitted when unconfirmed. Never inferred from the metro grouping."},"metro":{"type":"string","description":"Directory city/metro grouping, e.g. Dallas for a venue in Garland."},"facts":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","value","sourceUrl","checkedOn"],"properties":{"key":{"type":"string"},"value":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"}}},"description":"Sourced visitor facts. Empty means unconfirmed, not false."},"schedule":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["date","status","sourceUrl","checkedOn"],"properties":{"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["open","closed"]},"kind":{"type":"string","enum":["attraction_hours","ticket_window","departure"],"description":"Omitted legacy kind means attraction_hours. Ticket windows and departures never imply the attraction is open."},"opens":{"type":"string","description":"Venue local time, HH:MM. Never inferred from ticket-window hours."},"closes":{"type":"string","description":"Venue local time, HH:MM."},"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"}}},"description":"Sourced venue dates. Empty means schedule unconfirmed, not closed."},"priceOptions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["description","amount","currency","tax","sourceUrl","checkedOn"],"properties":{"description":{"type":"string","description":"Named admission product; not a universal minimum ticket price."},"amount":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{2})?$"},"currency":{"type":"string","enum":["USD","CAD","AUD","GBP","EUR","MXN","ARS","CLP","COP"]},"tax":{"type":"string","enum":["additional","included","unknown"],"description":"Tax treatment only. Additional booking fees may apply; confirm with the venue."},"sourceUrl":{"type":"string","format":"uri"},"checkedOn":{"type":"string","format":"date"}}},"description":"Named admission options, preserving currency, tax treatment, source and checked date. Empty means prices unconfirmed."},"website":{"type":"string","format":"uri"},"canonicalUrl":{"type":"string","format":"uri","description":"Canonical public HTML place URL."},"verified":{"type":"boolean","description":"True only when the licence has been validated; publication and Google grounding do not imply a validated licence."},"licenseValidationStatus":{"type":"string","enum":["validated","not_validated"]}}}}},"example":{"ok":true,"place":{"id":"haunt-us-co-denver-example-tour","name":"Example Ghost Tour","address":"100 Example St, Denver, CO 80202","city":"Denver","actualCity":"Denver","metro":"Denver","facts":[],"schedule":[],"priceOptions":[],"region":"CO","country":"US","category":"ghost-tours","website":"https://example.org/","verified":false,"licenseValidationStatus":"not_validated","canonicalUrl":"https://hountix.com/us/places/haunt-us-co-denver-example-tour"}}}}},"301":{"description":"Merged ID; Location points to the public canonical API record."},"400":{"description":"Malformed country code."},"404":{"description":"Unknown, held, unpublished, below-gate, wrong-country or other-product record."},"410":{"description":"Closed or tombstoned record."},"503":{"description":"Replica schema does not match the expected schema."}}}},"/claim/phone/request":{"post":{"operationId":"requestPhoneClaimOtp","responses":{"200":{"description":"Dispatches SMS verification code with sliding-window rate limit","content":{"application/json":{"example":{"ok":true,"claimId":"claim_123","phoneMasked":"(***) ***-0188","expiresAt":1730000000,"providerMessageId":"SM123456","fallbackTriggered":false,"dryRun":true}}}}}}},"/claim/phone/verify":{"post":{"operationId":"verifyPhoneClaimOtp","responses":{"200":{"description":"Verifies SMS OTP code and completes ownership challenge","content":{"application/json":{"example":{"ok":true,"claimId":"claim_123","status":"verified","verificationToken":"tok_claim_verified_123"}}}}}}},"/claim/domain/challenge":{"post":{"operationId":"getDomainClaimChallenge","responses":{"200":{"description":"Generates DNS TXT record challenge for domain verification","content":{"application/json":{"example":{"ok":true,"domain":"example.com","dnsRecord":{"type":"TXT","name":"_directory-challenge","value":"challenge_token_123"}}}}}}}},"/claim/domain/verify":{"post":{"operationId":"verifyDomainClaim","responses":{"200":{"description":"Validates DNS TXT record challenge for website domain ownership","content":{"application/json":{"example":{"ok":true,"domain":"example.com","status":"verified"}}}}}}},"/inquire":{"post":{"operationId":"submitLeadInquiry","responses":{"200":{"description":"Submits a consumer lead quote or consultation inquiry with honeypot spam protection","content":{"application/json":{"example":{"ok":true,"inquiryId":"inq_12345","status":"received"}}}}}}},"/api/v1/claims":{"post":{"operationId":"submitClaim","responses":{"200":{"description":"Submit an ownership or management claim for a published business listing","content":{"application/json":{"example":{"ok":true,"claimId":"claim-12345","status":"pending","submittedAt":"2026-10-21T00:00:00.000Z"}}}}}}},"/api/v1/claims/status":{"get":{"operationId":"getClaimStatus","responses":{"200":{"description":"Check the review status of a submitted listing claim","content":{"application/json":{"example":{"claimId":"claim-12345","status":"approved","updatedAt":"2026-10-21T00:00:00.000Z"}}}}}}},"/api/v1/editions":{"get":{"operationId":"listEditorialEditions","responses":{"200":{"description":"Localized tourism editorial editions (NYC, Miami, Mexico, Global)","content":{"application/json":{"example":{"activeEdition":"global","editions":[{"id":"nyc","brandName":"FinderNYC","domain":"findernyc.com","cityLabel":"New York City","countryCode":"us","language":"en"}]}}}}}}},"/api/v1/spots":{"get":{"operationId":"listEditorialSpots","description":"Existing editorial record inventory, independent of featured approval. Each item includes recordId, selections (recordId, cityId, rank, headline, reason, groups, state), and review: kind (venue, neighborhood-guide, workshop, route), status (needs-review, source-reviewed, held), optional canonicalName, identitySource, address/hours/admission/reservation facts (text, sourceUrl, checkedAt), lastChecked, author/reviewer only when documented, conflict, and image (url, alt, credit, license, optional sourceUrl and licenseUrl) or text-only disposition/reason. Legacy unsubstantiated health and registry badges are omitted. The same review supplies HTML facts.","responses":{"200":{"description":"Curated insider city spots filtered by edition, country, city, category, vibe, or neighborhood","content":{"application/json":{"example":{"total":1,"items":[{"slug":"bistrot-paul-bert-paris-11e","edition":"global","country":"fr","category":"restaurant","city":"Paris","title":"Iconic Zinc-Counter Parisian Bistrot in the 11th Arrondissement","replicaPlaceHref":"/fr/places/fr-alim-7511101","registryBadge":"Alim'confiance · FR-ALIM-7511101"}]}}}}}}},"/api/v1/spots/{slug}":{"get":{"operationId":"getEditorialSpot","description":"Shared existing record with the same recordId, review, fact sources and selections documented by listEditorialSpots. Unresolved records remain reachable without featured endorsement.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"item (editorial record with review metadata), chains (existing route references)","content":{"application/json":{"example":{"item":{"slug":"wynwood-back-alley-indie-galleries","recordId":"editorial-wynwood-back-alley-indie-galleries","name":"Bakehouse Art Complex","review":{"kind":"venue","status":"source-reviewed","identitySource":"https://www.bacfl.org/visit","lastChecked":"2026-10-26"},"selections":[]},"chains":[]}}}},"404":{"description":"Unknown record"}}}},"/api/v1/workshops":{"get":{"operationId":"listEditorialWorkshops","responses":{"200":{"description":"Hands-on creative workshops, classes, and masterclasses filtered by format, skill level, edition, or city","content":{"application/json":{"example":{"total":1,"items":[{"slug":"la-mano-pottery-chelsea","edition":"nyc","country":"us","category":"workshop","city":"New York City","title":"Beginner Wheel-Throwing & Handbuilding Classes in Chelsea","insider":{"activityDetails":{"providerName":"La Mano Pottery","skillLevel":"beginner","format":"one-off","duration":"2 hours","totalCost":"$95 all-inclusive (tuition + clay + glaze + 2 firings)","priceAmount":95,"currency":"USD"}},"scheduleStatus":{"isStale":false,"displayText":"Check provider schedule"}}]}}}}}}},"/api/v1/activities":{"get":{"operationId":"listEditorialActivities","responses":{"200":{"description":"Creative activities, drop-in making, and maker spaces filtered by format, skill level, edition, or city","content":{"application/json":{"example":{"total":1,"items":[{"slug":"makerspace-nyc-brooklyn-navy-yard","edition":"nyc","country":"us","category":"activity","city":"New York City","title":"Open Woodworking & Fabrication Studio at Brooklyn Navy Yard","insider":{"activityDetails":{"providerName":"MakerSpace NYC","skillLevel":"beginner","format":"one-off","duration":"2.5 hours","totalCost":"$85 (safety orientation + tools + practice wood)","priceAmount":85,"currency":"USD"}},"scheduleStatus":{"isStale":false,"displayText":"Next session: 2026-10-26 18:00 (EDT)"}}]}}}}}}},"/api/v1/spots/{slug}/schedule":{"post":{"operationId":"updateSpotSchedule","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Update workshop or activity verified schedule, next session date, and booking link","content":{"application/json":{"example":{"ok":true,"slug":"la-mano-pottery-chelsea","item":{"slug":"la-mano-pottery-chelsea","scheduleStatus":{"isStale":false,"displayText":"Next session: 2026-10-28 14:00 (EDT)"}},"receipt":{"updatedAt":"2026-10-21T23:00:00Z","providerEmail":"studio@lamanopottery.com","verifiedSchedule":"2026-10-28T14:00:00Z","status":"Next session: 2026-10-28 14:00 (EDT)"}}}}}}}},"/api/v1/spots/{slug}/inquire":{"post":{"operationId":"inquireSpot","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Submit a waitlist or private group booking inquiry for a workshop or activity","content":{"application/json":{"example":{"ok":true,"leadId":"inq_1729560000000","status":"received","spotSlug":"la-mano-pottery-chelsea","message":"Inquiry received for La Mano Pottery"}}}}}}},"/api/v1/neighborhoods":{"get":{"operationId":"listEditorialNeighborhoods","responses":{"200":{"description":"Neighborhood vibe guides filtered by edition, country, city, or area","content":{"application/json":{"example":{"total":1,"items":[{"slug":"east-village","edition":"nyc","country":"us","city":"New York City","name":"East Village","area":"Manhattan, NY"}]}}}}}}},"/api/v1/chains":{"get":{"operationId":"listLocalChains","responses":{"200":{"description":"Curated 3-stop local walking routes filtered by edition, country, city, neighborhood, spot, or mood","content":{"application/json":{"example":{"total":1,"items":[{"slug":"lic-sunset-to-astoria-feast","edition":"nyc","country":"us","title":"Queens Golden Hour to Greek Seafood Feast","neighborhood":"Long Island City","mood":"Sunset Views & Chill Drinks"}]}}}}}}},"/api/v1/chains/{slug}":{"get":{"operationId":"getLocalChain","description":"Retains route identity and exports. review.kind is route, status is held until ordered stop identities, compatible schedules and pedestrian travel are checked; conflict explains unresolved evidence. Unverified sequences are inspiration guides.","responses":{"200":{"description":"A curated 3-stop walking route with connected stops and notes","content":{"application/json":{"example":{"item":{"slug":"chelsea-clay-and-high-line-walk","title":"Chelsea Pottery Workshop, High Line Stroll & Bistro Dinner","neighborhoodSlug":"chelsea","neighborhoodLabel":"Chelsea · New York"}}}}},"404":{"description":"Chain not found","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/chains/{slug}/route.geojson":{"get":{"operationId":"getLocalChainGeoJson","responses":{"200":{"description":"RFC 7946 GeoJSON FeatureCollection containing Point coordinates and LineString path","content":{"application/geo+json":{"example":{"type":"FeatureCollection","features":[]}}}},"404":{"description":"Chain not found","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/itineraries":{"get":{"operationId":"listEditorialItineraries","responses":{"200":{"description":"Curated 1-to-3 day micro-itineraries pairing artisan craft workshops, dining, and walking routes","content":{"application/json":{"example":{"total":1,"items":[{"slug":"nyc-creative-craft-and-culinary-weekend","title":"NYC Creative Craft & Culinary Weekend: Chelsea to Brooklyn Waterfront","city":"New York City","country":"us","durationDays":2}]}}}}}}},"/api/v1/itineraries/{slug}":{"get":{"operationId":"getEditorialItinerary","responses":{"200":{"description":"Full time-blocked itinerary breakdown with spot guides and connected chains","content":{"application/json":{"example":{"item":{"slug":"nyc-creative-craft-and-culinary-weekend","title":"NYC Creative Craft & Culinary Weekend: Chelsea to Brooklyn Waterfront","city":"New York City","country":"us","durationDays":2,"highlights":["Wheel-throwing ceramics in Chelsea"],"timeBlocks":[]}}}}},"404":{"description":"Itinerary not found","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/itineraries/{slug}/schedule.ics":{"get":{"operationId":"getEditorialItineraryIcs","responses":{"200":{"description":"RFC 5545 iCalendar schedule export for multi-day itinerary time blocks","content":{"text/calendar":{"example":"BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Hidden City Gems//Itinerary Schedule//EN\r\nEND:VCALENDAR"}}},"404":{"description":"Itinerary not found","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/billing/checkout":{"post":{"operationId":"startCheckout","security":[{"staff":[]}],"responses":{"404":{"description":"Disabled until the page row and the host secret exist","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/mcp":{"post":{"operationId":"callExternalMcp","security":[{"staff":[]}],"responses":{"200":{"description":"External tools whose handlers finish","content":{"application/json":{"example":{"tools":["health","listings.search"]}}}}}}},"/privacy":{"get":{"operationId":"getPrivacy","responses":{"200":{"description":"Privacy fixture","content":{"text/html":{"example":"<h1>Privacy</h1>"}}}}}},"/terms":{"get":{"operationId":"getTerms","responses":{"200":{"description":"Terms fixture","content":{"text/html":{"example":"<h1>Terms</h1>"}}}}}},"/robots.txt":{"get":{"operationId":"getRobots","responses":{"200":{"description":"Crawler policy with no sitemap line","content":{"text/plain":{"example":"User-agent: *\nDisallow:\n"}}}}}},"/api/admin/billing/pages":{"get":{"operationId":"listBillingPages","security":[{"staff":[]}],"responses":{"200":{"description":"Page rows without secrets","content":{"application/json":{"example":{"pages":[],"webhook":false}}}}}},"put":{"operationId":"putBillingPage","security":[{"staff":[]}],"responses":{"400":{"description":"Rejected when the host has no Stripe secret","content":{"application/json":{"example":{"status":400}}}}}}},"/api/admin/audits":{"get":{"operationId":"listAudits","security":[{"staff":[]}],"responses":{"200":{"description":"Audit rows","content":{"application/json":{"example":{"audits":[]}}}}}}},"/api/admin/staff/grant":{"post":{"operationId":"grantStaff","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"status":401}}}}}}},"/api/admin/staff/revoke":{"post":{"operationId":"revokeStaff","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"status":401}}}}}}},"/api/admin/mcp":{"post":{"operationId":"callInternalMcp","security":[{"staff":[]}],"responses":{"200":{"description":"Internal tool call, dry-run unless dryRun is false","content":{"application/json":{"example":{"dryRun":true}}}}}}},"/admin":{"get":{"operationId":"getAdmin","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"error":"unauthorized"}}}}}}},"/health/deep":{"get":{"operationId":"getHealthDeep","responses":{"200":{"description":"Deep health check with edge telemetry and moderation counters","content":{"application/json":{"example":{"ok":true,"status":"healthy","host":"homecrafto.com","brand":"HomeCrafto","vertical":"trade","edge":{"colo":"EWR","country":"US","uptimeSeconds":3600},"outbox":{"indexNowPending":0,"claimsPending":0},"rateLimiter":{"trackedIps":0}}}}}}}},"/api/v1/telemetry/metrics":{"get":{"operationId":"getTelemetryMetrics","responses":{"200":{"description":"Real-time aggregated edge performance and request telemetry","content":{"application/json":{"example":{"totalRequests":100,"statusBreakdown":{"2xx":95,"3xx":2,"4xx":3,"5xx":0},"latency":{"p50":1.2,"p95":14.5,"mean":2.1,"min":0.1,"max":25},"botBreakdown":{"human":80,"searchEngine":15,"aiScraper":5,"malicious":0},"cacheHitRatio":0.85,"zeroTokenSpendVerified":true,"timestamp":"2026-10-21T12:00:00.000Z"}}}}}}},"/api/v1/telemetry/logpush":{"get":{"operationId":"getTelemetryLogpush","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Buffered structured Cloudflare Logpush event stream","content":{"application/json":{"example":{"ok":true,"count":1,"events":[{"Event":"WorkerRequest","EventTimestampMs":1729512000000,"Outcome":"ok","RayId":"9a12b34c-EWR","Script":"directory-pet","Request":{"Method":"GET","URL":"https://sociablepet.com/us/ct/stamford","Country":"US","Colo":"EWR"},"Response":{"Status":200,"DurationMs":1.5,"CacheStatus":"HIT"},"Metadata":{"Brand":"pet","BotType":"human","ZeroTokenSpend":true}}]}}}}}}},"/api/v1/claim/magic-link":{"post":{"operationId":"postClaimMagicLink","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claimId","email"],"properties":{"claimId":{"type":"string"},"email":{"type":"string"}}},"example":{"claimId":"claim_123","email":"owner@example.com"}}}},"responses":{"200":{"description":"Cryptographically signed magic link for provider self-service","content":{"application/json":{"example":{"ok":true,"claimId":"claim_123","magicUrl":"https://homecrafto.com/claim/magic-verify?token=example_token","status":"pending"}}}}}}},"/staff/login":{"get":{"operationId":"getStaffLogin","security":[{"staff":[]}],"responses":{"200":{"description":"Buttons hidden until that host has a client id","content":{"application/json":{"example":{"google":false,"apple":false,"password":false}}}}}}}},"components":{"securitySchemes":{"staff":{"type":"apiKey","in":"cookie","name":"directory_session"}}},"servers":[{"url":"https://halloween.chat","description":"Halloween.chat edge production network"}]}