booksy_businesses
List one page of Booksy's salon and barber marketplace for a country, filtered by a top-level category id, a treatment id, a free-text query or a comma-separated list of business ids, and optionally scoped to a Booksy location. Returns each business's id, name, address and coordinates, distance, aggregate review counters, primary category, promotion and badge flags, and cover image, plus the resolved location node, the marketplace total and whether a further page exists. Get category ids from booksy_categories and treatment ids from booksy_treatment_hints; both are INTEGER ids and a slug is rejected, and they may be combined. The app's own listing filters are accepted too: sort_order is one of distance, score, top_rated or by_ids, where by_ids requires business_ids and returns the businesses in that supplied order, and score is the marketplace default ranking and changes nothing; gender is one of M, F or R and reorders the page for a stated client gender without filtering it, so the total is unchanged; open_now and has_special_offers are booleans that restrict the page to businesses open now or running a special offer; and business_ids is a comma-separated bulk lookup of at most 100 ids that also satisfies the requirement for one of category, treatment or query. At least one of category, treatment, query or business_ids is required. page_size is capped at 100, page 0 is rejected, and a page past the end is an honest empty array with the total intact. total saturates at 10000 and total_capped says when it is a ceiling. Read location in the response rather than trusting location_name, because an unknown name silently resolves to the whole country. Use booksy_business for one business's full record.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "booksy_businesses"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number, default 1. Page 0 is rejected locally because the upstream answers a validation error; a page past the end is an honest empty businesses array with the total intact. | |
| query | No | Optional free-text search term, for example braids or fades. At least one of category, treatment or query is required. | |
| gender | No | Optional ranking personalisation, one of: M (male), F (female), R (refused / not stated, Booksy's own neutral default). It reorders the page for a stated client gender but does NOT filter the match set, so the total is unchanged. Booksy silently ignores an unrecognised value, so it is validated here instead of upstream. | |
| country | No | Optional Booksy market, one of: ar, au, br, ca, cl, co, de, es, fr, gb, ie, it, mx, nl, pl, pt, us, za. Defaults to us. These are the only country hosts that serve this API; the app's other country hosts redirect to the website or do not resolve. | |
| category | No | Optional top-level category id from booksy_categories, for example 6 for Barber or 1 for Hair. It must be an INTEGER id: the upstream rejects a slug with a validation error. An id outside the 18-value enum answers an empty list rather than an error. | |
| open_now | No | Optional: true restricts the page to businesses open at the moment of the request. A pointer so that omitted and false are distinguishable. It is sent upstream as 1/0 because Booksy rejects true/false on this parameter. | |
| page_size | No | Records per page, default 20, maximum 100. Values above 100 are rejected because the upstream silently clamps them to 100. | |
| treatment | No | Optional treatment id from booksy_treatment_hints, for example 363 for Male Haircut. It must be an INTEGER id; a slug is rejected upstream. May be combined with category. | |
| sort_order | No | Optional listing order, one of: distance, score, top_rated, by_ids. distance orders by distance from the requested location, so it is only meaningful with location_id, location_name or location_geo; score is the marketplace's default ranking and returns the same order as sending no sort_order at all; top_rated orders by rating; by_ids returns businesses in business_ids' own order and therefore requires business_ids. | |
| location_id | No | Optional Booksy location id (city, region or country node), for example 30067 for New York City. Supply it instead of location_name. Learn ids from a previous response's location_details. | |
| business_ids | No | Optional comma-separated Booksy business ids for a bulk lookup, at most 100, for example 421547,646877. Every entry must be a positive integer. The businesses come back in the order supplied and the total is the number of ids that exist. This is the bulk-lookup form of the app client's sort_order=by_ids call, which requires business_ids. Supplying ids also satisfies the requirement for at least one of category, treatment or query. | |
| location_name | No | Optional location name for the server to resolve, for example New York City or Orlando. Supply it instead of location_id. An unknown name is not an error: the server silently falls back to the whole country, so always read the response's location_details to see what was applied. | |
| has_special_offers | No | Optional: true restricts the page to businesses running a special offer. A pointer so that omitted and false are distinguishable. It is sent upstream as true/false, which is the form this parameter accepts. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The tool result payload (shape varies per tool; see each tool's docs resource). |