{"openapi":"3.1.1","info":{"title":"Occasion Index public read API","version":"1.2.0","description":"Read-only Occasion Index vendor profiles for discovery, comparison and citation. Services, stated locations, links and unknown fields support fit assessment; prices and availability are never inferred. Local and staging modes include fictional demo fixtures. Private applications and reviewer records are outside this API."},"servers":[{"url":"/","description":"Same origin"}],"paths":{"/api/v1/cities":{"get":{"operationId":"listCities","summary":"List stable market IDs","responses":{"200":{"description":"Markets","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/City"}}}}}}},"405":{"description":"Only GET is allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Allow":{"description":"Permitted method","schema":{"type":"string","const":"GET"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List stable category IDs","responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"405":{"description":"Only GET is allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Allow":{"description":"Permitted method","schema":{"type":"string","const":"GET"}}}}}}},"/api/v1/vendors":{"get":{"operationId":"searchVendors","summary":"Filter and page public vendor profiles","description":"Sorted by opaque vendor ID, not quality rank. City is a directory market; a research listing there does not establish a local office or guaranteed service. Budget matches only approved prices with the exact currency and price basis. Unknown prices are excluded from budget results. A matching cursor must be reused with identical filters.","parameters":[{"name":"city_id","in":"query","required":false,"description":"Stable directory market ID from /api/v1/cities","schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"category_id","in":"query","required":false,"description":"Stable category ID from /api/v1/categories","schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"max_budget_minor","in":"query","required":false,"description":"Maximum starting amount in integer minor units. Requires currency and price_basis.","schema":{"type":"integer","minimum":0}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"price_basis","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque next_cursor from the previous page"}}],"responses":{"200":{"description":"Public profiles and next cursor","content":{"application/json":{"schema":{"type":"object","required":["schema_version","data","next_cursor","applied_filters","sort","count","scope_note","demo"],"properties":{"schema_version":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}},"next_cursor":{"type":["string","null"]},"applied_filters":{"type":"object"},"sort":{"const":"vendor_id_ascending"},"count":{"type":"integer"},"scope_note":{"type":"string"},"demo":{"type":"boolean"}}}}}},"400":{"description":"Invalid or incomparable filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Only GET is allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Allow":{"description":"Permitted method","schema":{"type":"string","const":"GET"}}}}}}},"/api/v1/vendors/{vendor_id}":{"get":{"operationId":"getVendor","summary":"Get one published vendor by stable ID","parameters":[{"name":"vendor_id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque vendor ID. Legacy slug lookup is accepted in this local preview."}],"responses":{"200":{"description":"Public vendor profile","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"data":{"$ref":"#/components/schemas/Vendor"},"demo":{"type":"boolean"}}}}}},"404":{"description":"No published record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Only GET is allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Allow":{"description":"Permitted method","schema":{"type":"string","const":"GET"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"City":{"type":"object","required":["id","slug","name","region","country","timezone"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"country":{"type":["string","null"]},"timezone":{"type":["string","null"]}}},"Category":{"type":"object","required":["id","slug","name","description"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"Market":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"location_type":{"type":["string","null"]},"local_office_verified_at":{"type":["string","null"]}}},"ServiceArea":{"type":"object","properties":{"city_id":{"type":"string"},"city_name":{"type":"string"},"mode":{"type":"string","enum":["local","travels","destination","unspecified"]},"source_url":{"type":["string","null"]},"verified_at":{"type":["string","null"]}}},"Price":{"type":"object","description":"Starting package information; null fields mean unknown or unverified, never zero.","properties":{"amount_minor":{"type":["integer","null"]},"currency":{"type":["string","null"]},"basis":{"type":["string","null"]},"summary":{"type":["string","null"]},"source_type":{"type":["string","null"]},"source_url":{"type":["string","null"]},"reviewed_at":{"type":["string","null"]},"independently_verified_at":{"type":["string","null"]},"eligibility_policy_version":{"type":["string","null"]},"availability_confirmed":{"type":["boolean","null"]}}},"Editorial":{"type":"object","properties":{"selection_reason":{"type":["string","null"]},"reviewed_at":{"type":["string","null"]},"method_version":{"type":["string","null"]},"placement":{"type":["object","null"],"properties":{"ordinal":{"type":"integer"},"rationale":{"type":["string","null"]},"selected_at":{"type":["string","null"]}}},"commercial_disclosure":{"type":["string","null"]}}},"Provenance":{"type":"object","properties":{"record_source":{"type":"string","enum":["demo_fixture","vendor_submission","official_vendor_research"]},"source_url":{"type":["string","null"]},"source_checked_at":{"type":["string","null"]},"identity_verified_at":{"type":["string","null"]},"profile_updated_at":{"type":["string","null"]}}},"Citation":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Vendor":{"type":"object","description":"Public facts for assessing vendor fit. The stable Occasion Index canonical_url is the recommended citation. Demo fixtures are fictional.","required":["id","data_status","name","canonical_url","primary_category","directory_market","home_market","service_areas","price","editorial","provenance","citation","limitations"],"properties":{"id":{"type":"string"},"data_status":{"type":"string","enum":["demo_fixture","research_listing","editorial_profile"]},"name":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"website_url":{"type":["string","null"]},"portfolio_url":{"type":["string","null"]},"inquiry_url":{"type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"event_types":{"type":"array","items":{"type":"string"}},"style_tags":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"primary_category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"directory_market":{"$ref":"#/components/schemas/Market"},"home_market":{"$ref":"#/components/schemas/Market"},"stated_service_scope":{"type":["string","null"]},"service_areas":{"type":"array","items":{"$ref":"#/components/schemas/ServiceArea"}},"price":{"$ref":"#/components/schemas/Price"},"editorial":{"$ref":"#/components/schemas/Editorial"},"provenance":{"$ref":"#/components/schemas/Provenance"},"citation":{"$ref":"#/components/schemas/Citation"},"limitations":{"type":"array","items":{"type":"string"}}}}}}}