{"openapi":"3.1.0","info":{"title":"Agent Bookability Index API","version":"0.3.11","description":"Published facts about New York area private-event vendors (photographers, DJs, caterers, florists, planners, videographers, live bands, photo booths, hair and makeup, cakes): starting prices with what they cover, areas served, event types, and how to book, each read from the vendor's own website with the page it came from. Also median prices by category and area.\nTypical flow: shortlist_vendors for an event (or search_vendors for one category), then get_vendor or compare_vendors for details, get_price_summary to say what a service usually costs, and estimate_event_budget for what all the services together usually cost.\nAreas: a borough, NYC, Long Island, Westchester, North or Central Jersey, New Jersey, or a county or town in them (Bergen County, Hoboken). Needs: kosher, halal, MC, lighting, photo booth, second shooter and more (list_categories lists them). For the cheapest options, search_vendors with sort=price; mind each price's unit (per event, hour or guest).\nWhen you use a fact, cite the index_page or source given and say the date it was checked. Prices are what vendors publish, not quotes; the consumer confirms with the vendor using the booking route shown.\nNo key or sign-up. The same tools are on the MCP server at https://index.therunup.ai/mcp .","contact":{"email":"info@therunup.ai"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://index.therunup.ai"}],"paths":{"/api/list_categories":{"get":{"operationId":"list_categories","summary":"List vendor categories","description":"What the index covers: the vendor categories with how many vendors each has, how many publish a price and the median published starting price for a whole event; the areas, event types and needs (kosher, MC, lighting...) the other tools accept. Call it first if you are unsure what the index covers.","parameters":[],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/CategoryRow"},"title":"Categories","type":"array"},"areas":{"items":{"type":"string"},"title":"Areas","type":"array"},"event_types":{"items":{"type":"string"},"title":"Event Types","type":"array"},"needs":{"description":"Values the needs parameter accepts.","items":{"type":"string"},"title":"Needs","type":"array"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"As Of"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["categories","areas","event_types"],"title":"CategoryList","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/search_vendors":{"get":{"operationId":"search_vendors","summary":"Search vendors","description":"Find New York area event vendors, in one category or across all, filtered by area, event type, maximum published price, online booking or part of a name. Sorted by bookability score (how much an AI agent can learn and do on the vendor's own site), then price.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Vendor category in plain words (\"DJ\", \"wedding photographer\", \"florist\"). Omit to search every category."},{"name":"area","in":"query","required":false,"schema":{"type":"string"},"description":"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area."},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"},"description":"Optional event type in plain words: \"wedding\", \"bar mitzvah\", \"sweet 16\", \"birthday\", \"corporate holiday party\", \"baby shower\"."},{"name":"max_price_usd","in":"query","required":false,"schema":{"type":"number"},"description":"Only vendors whose published starting price is at or under this, in US dollars."},{"name":"has_price","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Only vendors that publish a price."},{"name":"books_online","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Only vendors whose own site shows online booking."},{"name":"name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Part of the vendor's name."},{"name":"needs","in":"query","required":false,"schema":{"items":{"type":"string"},"type":"array"},"description":"Optional things the vendor must offer, as its own website states: \"kosher\", \"halal\" (caterers), \"MC\", \"lighting\", \"photo booth\" (DJs, bands), \"second shooter\" (photographers), \"second videographer\", \"comes to you\" (hair and makeup), \"staff\" (caterers), \"delivery and setup\" (florists, cakes).","style":"form","explode":false},{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer"},"description":"How many vendors to return, 1 to 25 (larger values are capped)."},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer"},"description":"How many matches to skip, to page through a long list: pass next_offset from the previous result."},{"name":"sort","in":"query","required":false,"schema":{"default":"score","type":"string"},"description":"\"score\" (default: most bookable first, then price) or \"price\" (lowest published starting price first, vendors without a price last; check starting_price.per, as a per-hour or per-guest rate is not a whole-event price)."}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Area"},"matched":{"description":"How many vendors matched before the limit.","title":"Matched","type":"integer"},"shown":{"title":"Shown","type":"integer"},"offset":{"default":0,"description":"How many matches were skipped before these.","title":"Offset","type":"integer"},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pass this as offset to get the next page; None when there is no more.","title":"Next Offset"},"vendors":{"items":{"$ref":"#/components/schemas/VendorCard"},"title":"Vendors","type":"array"},"list_page":{"description":"The index page listing these vendors.","title":"List Page","type":"string"},"note":{"title":"Note","type":"string"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["category","area","matched","shown","vendors","list_page","note"],"title":"SearchVendorsResult","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/shortlist_vendors":{"get":{"operationId":"shortlist_vendors","summary":"Shortlist vendors for an event","description":"A shortlist for one event: for each service asked for, the best few New York area vendors that serve the area and event type. Ranked by how directly a consumer can act (book online, instant quote or open dates, quote form), then by fit with the budget, bookability score and price.","parameters":[{"name":"categories","in":"query","required":true,"schema":{"items":{"type":"string"},"type":"array"},"description":"The services needed, in plain words, e.g. [\"DJ\", \"photographer\", \"florist\"]. Up to 6. Comma-separated.","style":"form","explode":false},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"},"description":"Optional event type in plain words: \"wedding\", \"bar mitzvah\", \"sweet 16\", \"birthday\", \"corporate holiday party\", \"baby shower\"."},{"name":"area","in":"query","required":false,"schema":{"type":"string"},"description":"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area."},{"name":"budget_usd","in":"query","required":false,"schema":{"type":"number"},"description":"Optional budget per service, US dollars. Vendors whose published starting price fits come first."},{"name":"per_category","in":"query","required":false,"schema":{"default":3,"type":"integer"},"description":"Vendors per service, 1 to 10."},{"name":"needs","in":"query","required":false,"schema":{"items":{"type":"string"},"type":"array"},"description":"Optional things the vendor must offer, as its own website states: \"kosher\", \"halal\" (caterers), \"MC\", \"lighting\", \"photo booth\" (DJs, bands), \"second shooter\" (photographers), \"second videographer\", \"comes to you\" (hair and makeup), \"staff\" (caterers), \"delivery and setup\" (florists, cakes).","style":"form","explode":false},{"name":"guests","in":"query","required":false,"schema":{"type":"integer"},"description":"Optional number of guests. Per-guest prices (catering, cakes) are worked out for this many."},{"name":"hours","in":"query","required":false,"schema":{"type":"number"},"description":"Optional length of the event in hours. Per-hour prices (some DJs, photographers, bands) are worked out for this long."}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Area"},"budget_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Budget Usd"},"guests":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Guests"},"hours":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Hours"},"groups":{"items":{"$ref":"#/components/schemas/ShortlistGroup"},"title":"Groups","type":"array"},"how_ranked":{"title":"How Ranked","type":"string"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["event_type","area","budget_usd","groups","how_ranked"],"title":"Shortlist","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/get_vendor":{"get":{"operationId":"get_vendor","summary":"Get one vendor","description":"Everything the index knows about one vendor: category, areas, bookability score, website, how to book, and every published fact (starting price and what it covers, packages, deposit, booking lead time, cancellation policy and more), each with the quote from the vendor's own site, its page and the.","parameters":[{"name":"vendor","in":"query","required":true,"schema":{"type":"string"},"description":"The vendor's name (or part of it), its index_page URL from another tool, or its slug such as \"448-studio\"."}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"name":{"title":"Name","type":"string"},"category":{"title":"Category","type":"string"},"areas":{"items":{"type":"string"},"title":"Areas","type":"array"},"score":{"title":"Score","type":"integer"},"price_from_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Price From Usd"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"index_page":{"title":"Index Page","type":"string"},"checked":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Checked"},"how_to_book":{"$ref":"#/components/schemas/Booking"},"facts":{"additionalProperties":{"$ref":"#/components/schemas/Fact"},"description":"Every published fact, by name (starting_price, packages, deposit...).","title":"Facts","type":"object"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["name","category","areas","score","index_page","how_to_book","facts"],"title":"VendorDetail","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/compare_vendors":{"get":{"operationId":"compare_vendors","summary":"Compare vendors","description":"Two to five vendors side by side: starting price and what it covers, areas, event types, deposit, booking lead time, cancellation policy and how to book, with every fact's source. Use it when a consumer is choosing between vendors from a search or shortlist.","parameters":[{"name":"vendors","in":"query","required":true,"schema":{"items":{"type":"string"},"type":"array"},"description":"2 to 5 vendors, each a name, index_page URL or slug. Comma-separated.","style":"form","explode":false}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"vendors":{"items":{"$ref":"#/components/schemas/VendorDetail"},"title":"Vendors","type":"array"},"side_by_side":{"description":"One row per vendor with the facts most used to choose.","items":{"additionalProperties":true,"type":"object"},"title":"Side By Side","type":"array"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["vendors","side_by_side"],"title":"Comparison","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/get_price_summary":{"get":{"operationId":"get_price_summary","summary":"Price summary for a service","description":"One service's price: what New York area vendors in one category publish as a starting price for a whole event: the median and the middle half (25th to 75th percentile), from how many vendors and when, optionally for one area, plus per-hour or per-guest figures where the category is priced that way.","parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"description":"Vendor category in plain words: \"photographers\", \"DJ\", \"caterer\", \"florist\", \"planner\", \"live band\", \"videographer\", \"photo booth\", \"hair and makeup\" or \"cakes\". list_categories gives the full list."},{"name":"area","in":"query","required":false,"schema":{"type":"string"},"description":"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area."}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"category":{"title":"Category","type":"string"},"area":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Area"},"area_note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Set when the area had too few prices and the whole region is used.","title":"Area Note"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"As Of"},"vendors":{"description":"How many vendors' published prices the figures come from.","title":"Vendors","type":"integer"},"low_quartile":{"title":"Low Quartile","type":"number"},"median":{"title":"Median","type":"number"},"high_quartile":{"title":"High Quartile","type":"number"},"per_unit":{"items":{"$ref":"#/components/schemas/UnitStat"},"title":"Per Unit","type":"array"},"sentence":{"description":"One sentence with the figures, made to be quoted whole.","title":"Sentence","type":"string"},"source":{"title":"Source","type":"string"},"cost_pages":{"description":"More specific index pages answering what this costs (wedding, per hour, per guest), each with its quotable answer.","items":{"additionalProperties":{"type":"string"},"type":"object"},"title":"Cost Pages","type":"array"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["category","vendors","low_quartile","median","high_quartile","sentence","source"],"title":"PriceSummary","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}},"/api/estimate_event_budget":{"get":{"operationId":"estimate_event_budget","summary":"Budget for an event","description":"Several services together: what a whole event's vendors usually cost: for each service, the low, median and high published starting price in the area, worked out for the guests and hours given, and the sum.","parameters":[{"name":"categories","in":"query","required":true,"schema":{"items":{"type":"string"},"type":"array"},"description":"The services the event needs, in plain words, e.g. [\"DJ\", \"photographer\", \"caterer\", \"cake\"]. Up to 8. Comma-separated.","style":"form","explode":false},{"name":"area","in":"query","required":false,"schema":{"type":"string"},"description":"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area."},{"name":"guests","in":"query","required":false,"schema":{"type":"integer"},"description":"Number of guests. Catering and cakes, usually priced per guest, are worked out for this many."},{"name":"hours","in":"query","required":false,"schema":{"type":"number"},"description":"Length of the event in hours. Where a service has per-hour prices, they are worked out for this long."}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"properties":{"area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Area"},"guests":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Guests"},"hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hours"},"services":{"items":{"$ref":"#/components/schemas/BudgetLine"},"title":"Services","type":"array"},"total_low_usd":{"description":"Sum of each service's 25th percentile: a rough low end, not a quote.","title":"Total Low Usd","type":"number"},"total_median_usd":{"title":"Total Median Usd","type":"number"},"total_high_usd":{"description":"Sum of each service's 75th percentile: a rough high end.","title":"Total High Usd","type":"number"},"sentence":{"description":"One sentence with the total, made to be quoted whole.","title":"Sentence","type":"string"},"notes":{"items":{"type":"string"},"title":"Notes","type":"array"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"As Of"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["area","guests","hours","services","total_low_usd","total_median_usd","total_high_usd","sentence"],"title":"EventBudget","type":"object"}}}},"400":{"description":"Bad parameters; the error says what to pass."}}}}},"components":{"schemas":{"CategoryRow":{"properties":{"category":{"title":"Category","type":"string"},"vendors":{"title":"Vendors","type":"integer"},"with_price":{"title":"With Price","type":"integer"},"median_starting_price_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Median Starting Price Usd"},"list_page":{"title":"List Page","type":"string"}},"required":["category","vendors","with_price","list_page"],"title":"CategoryRow","type":"object"},"Booking":{"properties":{"online_booking":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The vendor's site lets you book online.","title":"Online Booking"},"shows_open_dates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The site shows dates that are still open.","title":"Shows Open Dates"},"instant_quote":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The site shows a price after choosing options.","title":"Instant Quote"},"quote_request_form":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The site has a form to ask for a quote.","title":"Quote Request Form"},"contact_methods":{"description":"Ways to reach the vendor shown on its site (form, email, phone...).","items":{"type":"string"},"title":"Contact Methods","type":"array"}},"title":"Booking","type":"object"},"Estimate":{"properties":{"total_usd":{"description":"Starting price for this event, US dollars, from the vendor's published rate.","title":"Total Usd","type":"number"},"basis":{"description":"How it was worked out, e.g. \"$35 per guest x 120 guests\".","title":"Basis","type":"string"}},"required":["total_usd","basis"],"title":"Estimate","type":"object"},"Price":{"properties":{"amount_usd":{"description":"The vendor's lowest published starting price, US dollars.","title":"Amount Usd","type":"number"},"per":{"default":"event","description":"What the price is per: \"event\", \"hour\" or \"guest\".","title":"Per","type":"string"},"covers":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"What the price covers, in the index's words.","title":"Covers"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The vendor's own page the price was read from.","title":"Source"}},"required":["amount_usd"],"title":"Price","type":"object"},"VendorCard":{"properties":{"name":{"title":"Name","type":"string"},"category":{"title":"Category","type":"string"},"areas":{"description":"Area keys the vendor serves.","items":{"type":"string"},"title":"Areas","type":"array"},"score":{"description":"Bookability score 0-100: how much an AI agent can learn and do on the vendor's site.","title":"Score","type":"integer"},"starting_price":{"anyOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}],"default":null},"how_to_book":{"$ref":"#/components/schemas/Booking"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"index_page":{"description":"The vendor's page on the index: cite this.","title":"Index Page","type":"string"},"checked":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the vendor's website was read (YYYY-MM-DD).","title":"Checked"},"estimate":{"anyOf":[{"$ref":"#/components/schemas/Estimate"},{"type":"null"}],"default":null,"description":"Only in shortlists: the published starting price worked out for this event's guests or hours. A starting point, not a quote."}},"required":["name","category","areas","score","how_to_book","index_page"],"title":"VendorCard","type":"object"},"ShortlistGroup":{"properties":{"category":{"title":"Category","type":"string"},"matched":{"title":"Matched","type":"integer"},"vendors":{"items":{"$ref":"#/components/schemas/VendorCard"},"title":"Vendors","type":"array"},"list_page":{"title":"List Page","type":"string"}},"required":["category","matched","vendors","list_page"],"title":"ShortlistGroup","type":"object"},"Fact":{"properties":{"value":{"description":"The value as recorded (text, number, list or object).","title":"Value"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The vendor's own page the fact was read from.","title":"Source"},"quote":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The words on that page (emails and phones masked).","title":"Quote"},"checked":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Checked"}},"required":["value"],"title":"Fact","type":"object"},"VendorDetail":{"properties":{"name":{"title":"Name","type":"string"},"category":{"title":"Category","type":"string"},"areas":{"items":{"type":"string"},"title":"Areas","type":"array"},"score":{"title":"Score","type":"integer"},"price_from_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Price From Usd"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"index_page":{"title":"Index Page","type":"string"},"checked":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Checked"},"how_to_book":{"$ref":"#/components/schemas/Booking"},"facts":{"additionalProperties":{"$ref":"#/components/schemas/Fact"},"description":"Every published fact, by name (starting_price, packages, deposit...).","title":"Facts","type":"object"},"cite_as":{"default":"Agent Bookability Index by The Runup (index.therunup.ai)","title":"Cite As","type":"string"}},"required":["name","category","areas","score","index_page","how_to_book","facts"],"title":"VendorDetail","type":"object"},"UnitStat":{"properties":{"unit":{"description":"\"per hour\" or \"per guest\".","title":"Unit","type":"string"},"vendors":{"title":"Vendors","type":"integer"},"low_quartile":{"title":"Low Quartile","type":"number"},"median":{"title":"Median","type":"number"},"high_quartile":{"title":"High Quartile","type":"number"}},"required":["unit","vendors","low_quartile","median","high_quartile"],"title":"UnitStat","type":"object"},"BudgetLine":{"properties":{"category":{"title":"Category","type":"string"},"low_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"25th percentile of published starting prices, for this event.","title":"Low Usd"},"median_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Median Usd"},"high_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"75th percentile, for this event.","title":"High Usd"},"basis":{"description":"How the figures were worked out, e.g. \"median $40 per guest x 120 guests\".","title":"Basis","type":"string"},"vendors":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"How many vendors' published prices the figures come from.","title":"Vendors"},"area":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Area the figures are for; None means the whole New York area.","title":"Area"},"source":{"title":"Source","type":"string"}},"required":["category","basis","source"],"title":"BudgetLine","type":"object"}}}}