{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Venue Scout NYC API","version":"1.0.0","description":"Independent NYC private-event venue discovery from a sourced CSV. All monetary figures are USD. The public reviewer key demo-key-venuescout works only when explicitly configured in VENUE_SCOUT_API_KEYS; it is not a secret or a built-in bypass. No booking or live availability checks are performed. All filters combine with AND. Query parameters must not repeat; unknown parameters and invalid values return 400."},"servers":[{"url":"https://venuescoutnyc.com","description":"Production origin after deploying this API"}],"tags":[{"name":"Venues","description":"Search and inspect sourced venues."},{"name":"Service","description":"Public service metadata."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/venues":{"get":{"operationId":"searchVenues","tags":["Venues"],"summary":"Search private event venues","description":"Returns the full match count and a page of venues. Sort order: published prices first, ascending lowest rental/minimum figure, then slug; contact-for-quote venues follow in slug order. Sorting applies even without max_price. Venue amenities can describe different rooms; combined filters do not guarantee a single room satisfies every condition.","parameters":[{"name":"borough","in":"query","required":false,"schema":{"type":"string","enum":["manhattan","brooklyn","queens"]},"description":"Borough match; case-insensitive.","example":"manhattan"},{"name":"neighborhood","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Case-insensitive substring; blank means no filter.","example":"East Village"},{"name":"min_capacity","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Match if a stated seated OR standing capacity is at least this number. Explicitly unknown capacity fields do not match. Numbers are used for filtering only; original strings remain unchanged. Capacities across rooms are never added.","example":40},{"name":"max_price","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":"USD threshold against the lowest explicit public rental fee or F&B minimum figure. Contact-for-quote venues are always retained. Priced venues sort first. Hourly, daily and session figures are not converted to event totals; deposits and identifiable extra charges are not base prices. A match is not a promise that the event will cost this amount.","example":5000},{"name":"outdoor","in":"query","required":false,"schema":{"type":"boolean","enum":[true]},"description":"Send true to require affirmative source wording. Omit to disable this filter; false is invalid. Unstated, negative or ambiguous availability does not match. Conditions and room limitations remain in the response.","example":true},{"name":"av_sound","in":"query","required":false,"schema":{"type":"boolean","enum":[true]},"description":"Send true to require affirmative source wording. Omit to disable this filter; false is invalid. Unstated, negative or ambiguous availability does not match. Conditions and room limitations remain in the response.","example":true},{"name":"private_kitchen","in":"query","required":false,"schema":{"type":"boolean","enum":[true]},"description":"Send true to require affirmative source wording. Omit to disable this filter; false is invalid. Unstated, negative or ambiguous availability does not match. Conditions and room limitations remain in the response.","example":true},{"name":"wheelchair","in":"query","required":false,"schema":{"type":"boolean","enum":[true]},"description":"Send true to require affirmative source wording. Omit to disable this filter; false is invalid. Unstated, negative or ambiguous availability does not match. Conditions and room limitations remain in the response.","example":true},{"name":"event_type","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Case-insensitive substring of event_types; blank means no filter. The source may contain negative qualifications, so read the returned text.","example":"wedding"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Case-insensitive substring of venue name; blank means no filter.","example":"Bobo"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Page size. Values outside 1–50 are rejected.","example":20},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0},"description":"Number of matched venues to skip. count is always the total before pagination.","example":0}],"responses":{"200":{"description":"Search results, including an empty list when there are no matches or offset is beyond the end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"},"example":{"count":21,"venues":[{"id":"the-sixth-floor-loft","name":"The Sixth Floor Loft","borough":"manhattan","neighborhood":"Flatiron District","address":"873 Broadway, Sixth Floor, New York, NY 10003","capacity_seated":"80 (Spacious Studio 2)","capacity_standing":"100 (Spacious Studio 2)","price":"Spacious Studio 2 rental from $400/hour (6-hour minimum) or $4,500/day; $250 cleaning fee","event_types":"Receptions; workshops; production shoots","amenities":{"outdoor":"rooftop for photo/film shoots only, separately available","av_sound":"PA, microphones and projector","private_kitchen":"guest prep area with oven, refrigerator and sink","wheelchair":"lift and wheelchair access listed; accessible toilets unavailable"},"booking_contact":"info@sixthfloorloft.com; 212-982-8113; https://www.sixthfloorloft.com/book","sources":{"name":["https://www.sixthfloorloft.com/spacious-studios-2"],"borough + neighborhood":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"address":["https://www.sixthfloorloft.com/spacious-studios-2"],"capacity seated":["https://www.sixthfloorloft.com/spacious-studios-2"],"capacity standing":["https://www.sixthfloorloft.com/spacious-studios-2"],"rental fee or F&B minimum (exact public figures only)":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"event types hosted":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"amenities (outdoor, AV/sound, private kitchen, wheelchair access)":{"outdoor":["https://www.sixthfloorloft.com/"],"AV/sound":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"private kitchen":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"wheelchair access":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"]},"booking contact (email, phone, or booking URL)":["https://www.sixthfloorloft.com/spacious-studios-2"],"independent/small-group evidence":["https://www.sixthfloorloft.com/"]}}]}}}},"400":{"description":"Invalid, repeated or unknown search parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryError"},"example":{"error":"invalid query","details":["limit must be an integer from 1 to 50."]}}}},"401":{"description":"Missing or invalid x-api-key header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid api key"}}}},"405":{"description":"Only GET and OPTIONS are supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method not allowed"}}},"headers":{"Allow":{"schema":{"type":"string","const":"GET, OPTIONS"}}}},"500":{"description":"Unexpected internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal error"}}}},"503":{"description":"The CSV is missing or invalid; no fabricated data is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"venue dataset unavailable"}}}}}}},"/api/venues/{id}":{"get":{"operationId":"getVenue","tags":["Venues"],"summary":"Get one venue by stable ID","description":"Returns the same venue object shape as a search result, with the original source map.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"description":"The exact id from a search result.","example":"the-sixth-floor-loft"}],"responses":{"200":{"description":"Venue found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"},"example":{"id":"the-sixth-floor-loft","name":"The Sixth Floor Loft","borough":"manhattan","neighborhood":"Flatiron District","address":"873 Broadway, Sixth Floor, New York, NY 10003","capacity_seated":"80 (Spacious Studio 2)","capacity_standing":"100 (Spacious Studio 2)","price":"Spacious Studio 2 rental from $400/hour (6-hour minimum) or $4,500/day; $250 cleaning fee","event_types":"Receptions; workshops; production shoots","amenities":{"outdoor":"rooftop for photo/film shoots only, separately available","av_sound":"PA, microphones and projector","private_kitchen":"guest prep area with oven, refrigerator and sink","wheelchair":"lift and wheelchair access listed; accessible toilets unavailable"},"booking_contact":"info@sixthfloorloft.com; 212-982-8113; https://www.sixthfloorloft.com/book","sources":{"name":["https://www.sixthfloorloft.com/spacious-studios-2"],"borough + neighborhood":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"address":["https://www.sixthfloorloft.com/spacious-studios-2"],"capacity seated":["https://www.sixthfloorloft.com/spacious-studios-2"],"capacity standing":["https://www.sixthfloorloft.com/spacious-studios-2"],"rental fee or F&B minimum (exact public figures only)":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"event types hosted":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"amenities (outdoor, AV/sound, private kitchen, wheelchair access)":{"outdoor":["https://www.sixthfloorloft.com/"],"AV/sound":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"private kitchen":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"],"wheelchair access":["https://www.tagvenue.com/us/rooms/new-york/86313/the-sixth-floor-loft/spacious-studio-2"]},"booking contact (email, phone, or booking URL)":["https://www.sixthfloorloft.com/spacious-studios-2"],"independent/small-group evidence":["https://www.sixthfloorloft.com/"]}}}}},"401":{"description":"Missing or invalid x-api-key header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid api key"}}}},"404":{"description":"Unknown venue ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"405":{"description":"Only GET and OPTIONS are supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method not allowed"}}},"headers":{"Allow":{"schema":{"type":"string","const":"GET, OPTIONS"}}}},"503":{"description":"The CSV is missing or invalid; no fabricated data is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"venue dataset unavailable"}}}}}}},"/api/health":{"get":{"operationId":"getHealth","tags":["Service"],"summary":"Check dataset availability","description":"Public. Returns the actual parsed venue count. An unavailable or invalid dataset returns 503.","security":[],"responses":{"200":{"description":"Dataset loaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"ok","venues":200,"version":"1.0.0"}}}},"405":{"description":"Only GET and OPTIONS are supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method not allowed"}}},"headers":{"Allow":{"schema":{"type":"string","const":"GET, OPTIONS"}}}},"503":{"description":"The CSV is missing or invalid; no fabricated data is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"venue dataset unavailable"}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenAPI","tags":["Service"],"summary":"Read this OpenAPI 3.1 specification","description":"Public. Examples are generated from the current dataset.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON document.","content":{"application/json":{"schema":{"type":"object","required":["openapi","info","paths"],"additionalProperties":true,"properties":{"openapi":{"type":"string","const":"3.1.0"},"info":{"type":"object"},"paths":{"type":"object"}}}}}},"405":{"description":"Only GET and OPTIONS are supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method not allowed"}}},"headers":{"Allow":{"schema":{"type":"string","const":"GET, OPTIONS"}}}},"503":{"description":"The CSV is missing or invalid; no fabricated data is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"venue dataset unavailable"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"A key configured in VENUE_SCOUT_API_KEYS. Missing or invalid keys return HTTP 401. Public review key: demo-key-venuescout (must be enabled by the operator)."}},"schemas":{"SourceMap":{"type":"object","minProperties":1,"description":"The unmodified CSV source map. Fact keys map to URL lists or nested fact maps (including individual amenities).","additionalProperties":{"anyOf":[{"type":"array","items":{"type":"string","format":"uri","pattern":"^https?://"}},{"$ref":"#/components/schemas/SourceMap"}]}},"Venue":{"type":"object","additionalProperties":false,"required":["id","name","borough","neighborhood","address","capacity_seated","capacity_standing","price","event_types","amenities","booking_contact","sources"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Stable ASCII slug derived only from the venue name. Name changes can change the ID; duplicate slugs fail dataset validation."},"name":{"type":"string","description":"Venue name as supplied in the CSV."},"borough":{"type":"string","enum":["manhattan","brooklyn","queens"]},"neighborhood":{"type":"string","description":"Neighborhood from the borough + neighborhood column."},"address":{"type":"string","description":"Address as supplied in the CSV."},"capacity_seated":{"type":"string","description":"Verbatim CSV wording, including room names, ranges, caveats, or not publicly stated."},"capacity_standing":{"type":"string","description":"Verbatim CSV wording; total occupancy is not treated as a stated standing capacity when that field is explicitly unknown."},"price":{"type":"string","description":"Verbatim public pricing text with USD rental/minimum figures and all conditions, or exactly contact for quote. This is not a numeric total or a booking quote."},"event_types":{"type":"string","description":"Verbatim event-types text. Restrictions remain visible; substring filtering is not an eligibility guarantee."},"amenities":{"type":"object","additionalProperties":false,"required":["outdoor","av_sound","private_kitchen","wheelchair"],"properties":{"outdoor":{"type":"string","description":"The CSV amenity description, preserving limitations and conditions; not a boolean. Unknown descriptions do not match true filters."},"av_sound":{"type":"string","description":"The CSV amenity description, preserving limitations and conditions; not a boolean. Unknown descriptions do not match true filters."},"private_kitchen":{"type":"string","description":"The CSV amenity description, preserving limitations and conditions; not a boolean. Unknown descriptions do not match true filters."},"wheelchair":{"type":"string","description":"The CSV amenity description, preserving limitations and conditions; not a boolean. Unknown descriptions do not match true filters."}}},"booking_contact":{"type":"string","description":"Verbatim email, telephone, or booking URL text supplied in the CSV."},"sources":{"$ref":"#/components/schemas/SourceMap"}}},"SearchResult":{"type":"object","additionalProperties":false,"required":["count","venues"],"properties":{"count":{"type":"integer","minimum":0},"venues":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Venue"}}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"QueryError":{"type":"object","additionalProperties":false,"required":["error","details"],"properties":{"error":{"type":"string","const":"invalid query"},"details":{"type":"array","items":{"type":"string"}}}},"Health":{"type":"object","additionalProperties":false,"required":["status","venues","version"],"properties":{"status":{"type":"string","const":"ok"},"venues":{"type":"integer","minimum":1},"version":{"type":"string","const":"1.0.0"}}}}}}