list_niches
What the catalogue knows, and where
The trades (niches) this catalogue holds near a place, by key, with how many businesses are inside the radius (default 15 miles).
Without `niche`: a compact list of keys. With `niche`: that trade in full — its tags, coverage and the conditions its businesses publish.
A `niche` that is not a key comes back with `variants` and why (a tag, a similar name, a meaning) — nothing is substituted: pick a key.
`detail: "full"` lists every trade in full.
Coverage: restaurants in Apollo Beach, Carrollwood, Gibsonton, Lutz (+10 more); florists in Apollo Beach, Austin, Aventura, Brickell (+21 more); clothing stores in Carrollwood, Hollywood, St. Petersburg, Tampa; furnitures in St. Petersburg, Tampa; jewelrys in St. Petersburg, Tampa; nail salons in Apollo Beach, Gibsonton, Lutz, Riverview (+3 more); jewelry and watch repairs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; mattresss in St. Petersburg, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; hair salons in Gibsonton, Riverview, Ruskin, St. Petersburg (+3 more); car dealers in Tampa; garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Riverview, St. Petersburg, Tampa; massages in St. Petersburg, Tampa, Temple Terrace; boat rentals in St. Petersburg, Tampa; truck repairs in Tampa; tailors in St. Petersburg, Tampa; liquor stores in Lutz, Tampa; shooting ranges in St. Petersburg, Tampa; unknown trades in Tampa; barbers in Apollo Beach, New York, Riverview, St. Petersburg (+2 more); butcher and seafood markets in Tampa; bakerys in Tampa, Temple Terrace; medical equipment rentals in Gibsonton, Riverview, Tampa; landscapings in St. Petersburg, Tampa; phone repairs in Apollo Beach, Tampa; spas in St. Petersburg, Tampa, Temple Terrace; coffee shops in Chicago, Tampa; plumbers in Apollo Beach, Brandon, Gibsonton, Lutz (+2 more); windows and doorss in Tampa; dance studios in St. Petersburg, Tampa; moverss in Tampa, Temple Terrace; carpet cl
Parametersnichedetaillocationradius_miles
list_cards
Every business of one trade near a place, in one fixed order — the shelf
Every business of ONE trade (`niche`: a key from list_niches, exactly) near `location`, default radius 15 miles, 20 a page.
The order is fixed and is not a ranking: independent businesses, then chains, then marketplaces; inside each, by distance (a trade that comes to the customer: published service area first).
`query` does NOT filter or reorder businesses: it chooses which ITEM each card shows. To find businesses that have an item, use search_catalog.
Each card: id, name, distance, phone, a few items, `next` (one action), and for what you pass — `needed_by`, `max_price`, `deliver_to` — a state: hours give open_then / closed_then / unknown (never a free slot); an item price within the budget is item_price_within_budget (the total is not known until priced).
`needed_by`: «today», «tomorrow 19:00», «after 15:00», an interval «tomorrow 08:00 to 17:00», a deadline «by 2026-11-20», a range «this week» — read the same way in every tool.
A `niche` that is not a key returns no cards and the variants to choose from.
Trades on the shelf: restaurant (1224) · florist (318) · hair salon (283) · gas station (278) · barber (230) · nail salon (211) · pizza (198) · bakery (197) · medical clinic (195) · print shop (194) · catering (177) · grocery (169) · auto repair (168) · storage (157) · clothing store (155) · pharmacy (149) · oil change (147) · beauty salon (141) · ev charging station (141) · bar (137) · massage (133) · insurance agent (131) · dentist (123) · optometrist (120) · appliance repair (119) · pet grooming (119) · furniture (113) · notary (111) · coffee shop (107) · hotel (105) · fuel delivery (102) · event venue (101) · parking (100) · real estate agent (98) · lawyer (97) · chiropractor (95) · accountant (94) · liquor store (92) · party rental (90) · body shop (89) · movers (86) · veterinarian (85) · plumber (82) · locksmith (80) · pressure washing (78) · pool service (77) · tutoring (76) · jewelry (75) · shipping and packing store (75) · towing (75) · electrician (74)
Parameterspagetagslimitnicherequiredquerydetailintentlocationrequiredmax_priceneeded_bydeliver_toproperties+1 more
find_business
A business by its name
One business the user NAMED, matched by its name near `location` (default radius 15 miles); typos, word order and punctuation are tolerated.
Not in the catalogue → `name_not_found`, and up to 5 nearby businesses that carry the name's distinctive word (never presented as the business asked for).
`intent`, `query`, `needed_by`, `deliver_to` shape the short card the same way as list_cards.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersnamerequiredqueryintentlocationneeded_bydeliver_toradius_miles
search_catalog
A match by meaning, for when the trade is not known — check its results on the cards
Search by what is wanted (an item, a dish, a service, in any language) near `location`, default radius 15 miles, when the trade is not known.
Each business shows its best-fitting items first; `match.fit` says how well: exact (the thing and every asked property), likely (the thing, a property not stated), property (the thing with another quantity or colour), partial (only its main word), none. `nothing_fitting` says so when nothing does.
Conditions you pass come back per business as met / violated / unknown (time: open_then / closed_then / unknown): the item's price is not the total, opening hours are not a delivery time, being near is not being served.
No `location` and nothing fitting → an empty list, not unrelated businesses from anywhere.
Coverage: restaurants in Apollo Beach, Carrollwood, Gibsonton, Lutz (+10 more); florists in Apollo Beach, Austin, Aventura, Brickell (+21 more); clothing stores in Carrollwood, Hollywood, St. Petersburg, Tampa; furnitures in St. Petersburg, Tampa; jewelrys in St. Petersburg, Tampa; nail salons in Apollo Beach, Gibsonton, Lutz, Riverview (+3 more); jewelry and watch repairs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; mattresss in St. Petersburg, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; hair salons in Gibsonton, Riverview, Ruskin, St. Petersburg (+3 more); car dealers in Tampa; garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Riverview, St. Petersburg, Tampa; massages in St. Petersburg, Tampa, Temple Terrace; boat rentals in St. Petersburg, Tampa; truck repairs in Tampa; tailors in St. Petersburg, Tampa; liquor stores in Lutz, Tampa; shooting ranges in St. Petersburg, Tampa; unknown trades in Tampa; barbers in Apollo Beach, New York, Riverview, St. Petersburg (+2 more); butcher and seafood markets in Tampa; bakerys in Tampa, Temple Terrace; medical equipment rentals in Gibsonton, Riverview, Tampa; landscapings in St. Peters
Parameterslimitqueryrequireddetaillocationmax_priceneeded_byonly_localpropertiesfulfillmentradius_milesonly_independent
get_card
One business in full: what it sells, what can be done, how it reaches you
Free. One business in full, in the same shape for every trade: who it is (name, trade, address,
telephone, e-mail, opening hours, time zone), everything it sells (up to 60 offerings, cheapest first),
the six actions with their links and `required_fields`, how the thing reaches the buyer (delivery,
pickup, on_site, at_customer — with the published area, the fee and the order deadline), and how fresh
each part of that is. `live_data` (platform, synced_at) when the shelf is the business’s own connected
system: then every offering carries `source: connector` with its variants (each with `inventory`: units in
stock as the platform counts them, null = unknown), and an action with method
`connected` is taken through place_order / book_slot on this door.
Use it when the user asks «can they deliver to me», «are they open now», «what else do they do», or
when search_catalog offered a business with nothing listed and the next step is a telephone call.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersidrequired
get_offering
One thing in full, with its price checked again right now
Free. One offering in full, with ONE live request to the shop asking for that item’s price and stock
right now (`live_check`). Call it before you quote a price to a person: a catalogue read yesterday is
yesterday’s price. One business is asked at most once every ten minutes however many of its offerings
you open, so walking a shop is one request and not twenty; `from_cache` and `checked_at` say which.
A price list, a menu or a quote form has no single-item door to ask (`ok: false` with the reason) and
the stored reading stands with its date.
Hand `action_url` to the user as it is, ref=versum included.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersidrequired
get_product
One thing in full (synonym of get_offering)
SYNONYM of get_offering, kept for agents that already know this name. A «product» is just an offering whose kind is `product`; the same id works in both.
Free. One offering in full, with ONE live request to the shop asking for that item’s price and stock
right now (`live_check`). Call it before you quote a price to a person: a catalogue read yesterday is
yesterday’s price. One business is asked at most once every ten minutes however many of its offerings
you open, so walking a shop is one request and not twenty; `from_cache` and `checked_at` say which.
A price list, a menu or a quote form has no single-item door to ask (`ok: false` with the reason) and
the stored reading stands with its date.
Hand `action_url` to the user as it is, ref=versum included.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersidrequired
get_business
One business in full (synonym of get_card)
SYNONYM of get_card, kept for agents that already know this name.
Free. One business in full, in the same shape for every trade: who it is (name, trade, address,
telephone, e-mail, opening hours, time zone), everything it sells (up to 60 offerings, cheapest first),
the six actions with their links and `required_fields`, how the thing reaches the buyer (delivery,
pickup, on_site, at_customer — with the published area, the fee and the order deadline), and how fresh
each part of that is. `live_data` (platform, synced_at) when the shelf is the business’s own connected
system: then every offering carries `source: connector` with its variants (each with `inventory`: units in
stock as the platform counts them, null = unknown), and an action with method
`connected` is taken through place_order / book_slot on this door.
Use it when the user asks «can they deliver to me», «are they open now», «what else do they do», or
when search_catalog offered a business with nothing listed and the next step is a telephone call.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersidrequired
quote_order
What an order would cost delivered to an address — asked of the shop’s own cart, nothing ordered
Prices ONE cart in the shop's own public cart (Shopify or WooCommerce) to ONE ZIP, with no personal data, and orders nothing: the cart is emptied afterwards.
Answers the items, delivery options with their prices, the subtotal and what stays unknown (tax and fees at checkout; the delivery date unless the cart names it — `delivery_date` asks for a day).
Other platforms answer «quote not available» with the reason and the order link.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersitemsoptionsquantitydeliver_torequiredvariant_idoffering_idrequireddelivery_date
check_availability
Ask the business’s own system: is it in stock now · which slots are free
Only for a business whose card shows `live_data` (its items come from its connected Shopify or Square,
not from a page read). For a product: the platform’s stock right now — `state: confirmed | refuted |
unknown` (unknown = the platform does not track stock, which is not «no»). For a service on a platform
with bookings: the free `slots` between `from` and `to` (default: the next 7 days), each with a
`start_at` that book_slot takes as it is — on the business’s own clock with its offset
(`timezone` names the zone; `start_at_utc` is the same instant). If the card’s `cannot` lists `book`,
the slots are information only and the answer says so. A business without a connection answers `not_connected`.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parameterstofromquantityvariant_idbusiness_idrequiredoffering_idrequired
place_order
Place an order in the business’s own system; the buyer pays on the platform’s checkout page
🔴 ACTS FOR THE USER: call it only after the user has explicitly agreed to this exact action (what, where, when, who) — never on your own judgement.
For a business whose card shows an `order` action with method `connected`. Shopify: returns the shop’s
own checkout link with these items and quantities already in the cart (`status: unknown`, `mode: cart`)
— no customer data is needed or passed, the buyer gives their details and pays on Shopify, and nothing
exists on the shop until they do. Square: an order with a payment link (no customer data either).
WhatsApp: a message to the owner (customer phone or email). Returns `order_id`, `status`, `checkout_url`
— HAND THE CHECKOUT URL TO THE USER AS IT IS: that page takes the money, Versum holds no card and charges
nothing. Stock is checked live first on a platform that tracks it; «not in stock» is an `unavailable`
error and no order or link is given. Send an `idempotency_key` of your own and keep it for a retry: the
same key returns the same answer and the same link (`repeated: true`), never a second one. Lines name
offerings by their card id (and `variant_id` when the card lists several). `status`: unknown (a cart
link: payment is on the platform’s side) · created (the platform holds it) · pending_owner (WhatsApp) ·
confirmed · declined · failed. Get the user’s explicit yes before calling this.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersnotelinesrequiredcustomerbusiness_idrequiredidempotency_key
book_slot
Book a slot in the business’s own calendar (Square Appointments)
🔴 ACTS FOR THE USER: call it only after the user has explicitly agreed to this exact action (what, where, when, who) — never on your own judgement.
For a service whose business’s card shows a `book` action with method `connected` and no `book` in its
`cannot` (a door the platform refuses for this account is marked there, with the reason, at every sync). Take a `start_at`
from check_availability (slots) and the platform books it for the named customer; the answer is the
platform’s own status (created = on the calendar awaiting confirmation · confirmed · declined). A time
the platform does not offer is an `unavailable` error and nothing is booked. Idempotent by
`idempotency_key` like place_order. Get the user’s explicit yes first.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersnotecustomerrequiredstart_atrequiredvariant_idbusiness_idrequiredoffering_idrequiredidempotency_key
order_status
What became of an order or a booking placed through this door
The status of an `order_id` from place_order or book_slot, asked of the platform again when it is not final (paid? confirmed? declined by the owner?). A Shopify cart link answers `unknown` — payment is on Shopify’s side and the shop does not report it here. Free.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersorder_idrequired
request_to_owner
Send a request to the business’s verified owner (not a booking until the owner confirms)
🔴 ACTS FOR THE USER: call it only after the user has explicitly agreed to this exact action (what, where, when, who) — never on your own judgement.
For a business that takes requests through Versum (a verified owner with Telegram, e-mail or WhatsApp). Sends what,
when, how many, which branch and the person’s name and contact. Requires `idempotency_key`: retrying with the same key
returns the same request. Answers: `sent` (delivered to the owner), `link_given` (WhatsApp: give `whatsapp_url` to the
person — THEY send it; nothing is sent yet), or `no_channel` with the business’s other doors. Then poll request_status.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersdatenotetimewhatrequiredbranchcustomerrequiredquantitybusiness_idrequiredidempotency_keyrequired
request_status
What became of a request to the owner: delivery and the owner’s outcome
Delivery (`sent` · `link_given` · `expired` · `failed`) and the owner’s outcome (`declined` · `other_time` + proposal · `available` = free but NOT booked · `confirmed` = booked). `confirmed: true` only when the owner booked it.
Follow the server instructions «HOW TO USE THE VERSUM CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.
Parametersrequest_idrequired
