{"openapi":"3.1.0","info":{"title":"Treasure Valley Fun Directory API","version":"1.0.0","termsOfService":"https://directory.treasurevalleyfun.com/developers/#terms","contact":{"name":"Treasure Valley Fun support","email":"support@treasurevalleyfun.com"},"description":"Read-only data on things to do in Idaho's Treasure Valley. Only verified records are returned. Every record includes source_url, last_verified, status and canonical_url. Times are America/Boise. Anonymous access, rate limited. MCP: POST /api/mcp (Streamable HTTP). Terms (Idaho law; commercial use allowed): attribution required, with a link to the directory/canonical_url plus a \"Get the free weekly Fun Guide\" link to https://www.treasurevalleyfun.com/subscribe. No bulk resale and no competing directories. Each response includes an attribution object."},"servers":[{"url":"https://directory.treasurevalleyfun.com/api/v1"}],"paths":{"/search":{"get":{"operationId":"search","summary":"Search listings and events","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"description":"City slug(s), comma-separated, e.g. boise,meridian"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug(s), comma-separated, e.g. date-night"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text match on name/description"},{"name":"free","in":"query","schema":{"type":"boolean"},"description":"Only free (verified) items"},{"name":"region","in":"query","schema":{"type":"string","default":"treasure-valley"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"when","in":"query","schema":{"type":"string","enum":["today","tomorrow","this-weekend","this-week"]},"description":"Relative range in America/Boise time"},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Boise local time, e.g. 2026-10-17 or 2026-10-17T18:00:00"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"type","in":"query","schema":{"type":"string","enum":["listing","event"]}},{"name":"attributes","in":"query","schema":{"type":"string"},"description":"Attribute slugs, comma-separated (all must match), e.g. family-friendly,outdoor"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/listings":{"get":{"operationId":"listListings","summary":"List places","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"description":"City slug(s), comma-separated, e.g. boise,meridian"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug(s), comma-separated, e.g. date-night"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text match on name/description"},{"name":"free","in":"query","schema":{"type":"boolean"},"description":"Only free (verified) items"},{"name":"region","in":"query","schema":{"type":"string","default":"treasure-valley"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"attributes","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingPage"}}}},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/listings/{id}":{"get":{"operationId":"getListing","summary":"One place by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingOne"}}}},"404":{"description":"Not found or not verified"},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/events":{"get":{"operationId":"listEvents","summary":"Upcoming events (expired events are never returned)","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"description":"City slug(s), comma-separated, e.g. boise,meridian"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug(s), comma-separated, e.g. date-night"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text match on name/description"},{"name":"free","in":"query","schema":{"type":"boolean"},"description":"Only free (verified) items"},{"name":"region","in":"query","schema":{"type":"string","default":"treasure-valley"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"when","in":"query","schema":{"type":"string","enum":["today","tomorrow","this-weekend","this-week"]},"description":"Relative range in America/Boise time"},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Boise local time, e.g. 2026-10-17 or 2026-10-17T18:00:00"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPage"}}}},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"One event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventOne"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/cities":{"get":{"operationId":"listCities","summary":"Covered cities","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generic"}}}},"429":{"description":"Rate limited (60 requests/min per IP)"}}}},"/categories":{"get":{"operationId":"listCategories","summary":"Categories and attribute vocabulary","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generic"}}}},"429":{"description":"Rate limited (60 requests/min per IP)"}}}}},"components":{"schemas":{"Provenance":{"type":"object","properties":{"source_url":{"type":"string"},"last_verified":{"type":["string","null"]},"status":{"type":"string","enum":["site_active","seasonal","operating_confirmed","temporarily_closed","closed","unknown","scheduled","past"],"description":"site_active = official website is live and matched on last_verified; it does NOT confirm current opening. operating_confirmed only when an official source states it is operating."},"verification_status":{"type":"string","enum":["site_active","seasonal","operating_confirmed","temporarily_closed","closed","unknown","scheduled","past"],"description":"site_active = official website is live and matched on last_verified; it does NOT confirm current opening. operating_confirmed only when an official source states it is operating."},"canonical_url":{"type":"string"},"paid_placement":{"type":"boolean"}}},"Listing":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"city":{"type":"object"},"categories":{"type":"array"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"hours":{"type":["string","null"]},"attributes":{"type":"array","items":{"type":"string"}},"age_suitability":{"type":"array"},"indoor_outdoor":{"type":["string","null"]},"accessibility":{"type":"array"},"booking_url":{"type":["string","null"]},"is_free":{"type":["boolean","null"]}}}]},"Event":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"timezone":{"type":"string"},"venue":{"type":"string"},"is_free":{"type":["boolean","null"]}}}]},"ListingPage":{"type":"object","properties":{"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}}},"EventPage":{"type":"object","properties":{"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}},"ListingOne":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/Listing"}}},"EventOne":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/Event"}}},"SearchResponse":{"type":"object","properties":{"total":{"type":"integer"},"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Listing"},{"$ref":"#/components/schemas/Event"}]}}}},"Generic":{"type":"object"}}}}