Versum Agent Assistant

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, Brandon, Carrollwood, Gibsonton (+11 more); clothing stores in Apollo Beach, Brandon, Carrollwood, Gibsonton (+3 more); florists in Apollo Beach, Austin, Aventura, Brickell (+21 more); jewelrys in Brandon, St. Petersburg, Tampa; furnitures in Brandon, St. Petersburg, Tampa; nail salons in Apollo Beach, Brandon, Carrollwood, Gibsonton (+6 more); auto parts stores in Lutz, Tampa; jewelry and watch repairs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; hair salons in Apollo Beach, Gibsonton, Greater Northdale, Odessa (+6 more); truck repairs in Tampa; mattresss in St. Petersburg, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; car dealers in Tampa; grocerys in St. Petersburg, Tampa; massages in Apollo Beach, Brandon, Gibsonton, Riverview (+3 more); event venues in Lutz, Riverview, St. Petersburg, Tampa; print shops in Riverview, St. Petersburg, Tampa, Temple Terrace; garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Apollo Beach, Riverview, St. Petersburg, Tampa; spas in Apollo Beach, Riverview, St. Petersburg, Tampa (+1 more); barbers in Apollo Beach, New York, Odessa, Riverview (+4 more); bakerys in St. Petersburg, Tampa, Temple Terrace; auto repairs in St. Petersburg, Tampa, Temple Terrace; music lessonss in St. Petersburg, Tampa; pool services in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; liquor stores in Lutz, Tampa; boat rentals in St. Petersburg, Tampa; tailors in St. Petersburg, Tampa; shooting ranges in Odessa, St. Petersburg, Tampa; butcher and seafood markets in Tampa; unknown trades in Tampa; cafes in Apollo Beach, Riverview, St. Petersburg, Tampa; moverss in Riverview, St. Petersburg, Tampa, Temple Terrace; landscapings in St. Petersburg, Tampa; medical equipment rentals in Gibsonton, Riverview, Tampa; dance studios in Gibsonton, St. Petersburg, Tampa; coffee shops in Chicago, Tampa; plumbers in Apollo Beach, Brandon, Gibsonton, Lutz (+3 more); phone repairs in Apollo Beach, Tampa; medical clinics in Apollo Beach, Riverview, St. Petersburg, Tampa; windows and doorss in Apollo Beach, Tampa; optometrists in Apollo Beach, Riverview, St. Petersburg, Tampa; carpet cleanings in Lutz, St. Petersburg, Tampa; electricians in Apollo Beach, Odessa, Riverview, Ruskin (+2 more); pizzas in Tampa, Temple Terrace; appliance repairs in Apollo Beach, Brandon, Clearwater, Gibsonton (+3 more); roofers in Tampa, Temple Terrace; oil changes in Gibsonton, Riverview, Ruskin, St. Petersburg (+1 more); accountants in Greater Northdale, Lutz, St. Petersburg, Tampa (+1 more); HVACs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; dentists in Apollo Beach, St. Petersburg, Tampa; barber-shops in Riverview, St. Petersburg, Tampa; car rentals in St. Petersburg, Tampa; chiropractors in Tampa; window cleanings in Apollo Beach, Gibsonton, Riverview, Ruskin (+3 more); wedding planners in Sun City Center, Tampa; med spas in Riverview, Tampa; insurance agents in Greater Northdale, St. Petersburg, Tampa; tattoo studios in Greater Northdale, Ruskin, St. Petersburg, Tampa; hair-salons in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; cleanings in Lutz, Riverview, St. Petersburg, Tampa; meal preps in St. Petersburg, Tampa; caterings in Riverview, St. Petersburg, Tampa, Temple Terrace; photographers in Apollo Beach, Lutz, St. Petersburg, Tampa; elder care and home cares in Tampa; notarys in Gibsonton, Riverview, St. Petersburg, Sun City Center (+1 more); motorcycle repairs in Tampa; travel agencys in St. Petersburg, Tampa; pharmacys in Tampa; locksmiths in Greater Northdale, Riverview, St. Petersburg, Tampa; yogas in Apollo Beach, Ruskin, St. Petersburg, Tampa; storages in Gibsonton, Riverview, Ruskin, Tampa; veterinarians in Lutz, St. Petersburg, Tampa, Thonotosassa; parkings in Ruskin, St. Petersburg, Tampa; ice cream shops in Riverview, Tampa, Temple Terrace; tree services in Odessa, St. Petersburg, Tampa; kids play centers in Brandon, Tampa; handymans in Apollo Beach, Ruskin, St. Petersburg, Tampa; shipping and packing stores in Tampa; driving schools in Tampa, Town 'N' Country; tutorings in Gibsonton, St. Petersburg, Tampa, Westchase; body shops in Tampa; physical therapys in Riverview, St. Petersburg, Tampa; daycares in Apollo Beach, Brandon, St. Petersburg, Tampa; pressure washings in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; cleaning services in Apollo Beach, Gibsonton, Riverview, Ruskin (+2 more); septic and well services in Apollo Beach, Gibsonton, Lutz, Tampa; car washs in Apollo Beach, Riverview, St. Petersburg, Tampa (+1 more); towings in St. Petersburg, Tampa; lawyers in St. Petersburg, Tampa; dog walking and pet sittings in Gibsonton, Lutz, Riverview, Tampa (+1 more); junk removals in Riverview, St. Petersburg, Tampa; dry cleaners in St. Petersburg, Tampa; painters in Kissimmee, St. Petersburg, Tampa; specialty grocery and farmers markets in St. Petersburg, Tampa; pet boardings in Apollo Beach, Tampa; real estate agents in Apollo Beach, St. Petersburg, Tampa, Westchase; auto glasss in Tampa; nail-salons in Tampa; bars in Pine Key, Tampa, Temple Terrace; pest controls in St. Petersburg, Sun City Center, Tampa; general contractors in Apollo Beach, St. Petersburg, Tampa; gas stations in Gibsonton, Riverview, Sun City Center, Tampa; fuel deliverys in Gibsonton, Riverview, Ruskin, Tampa; braids-locss in Tampa; fishing charter and boat tourss in Ruskin, St. Petersburg, Tampa; funeral homes in Tampa; juice bars in Riverview, Tampa; pet stores in Tampa; golf courses in St. Petersburg, Tampa; beauty salons in St. Petersburg, Tampa; servicess in Sunny Isles Beach; bowling and billiardss in St. Petersburg, Tampa; garage doors in Tampa; tire shops in Tampa; taxi and transfer services in Tampa; bike and jet ski rentals in Apollo Beach, Tampa; shoe repairs in Tampa; hotels in St. Petersburg, Tampa; EV charging stations in Tampa; pizzerias in Brooklyn; kids sports and activitiess in St. Petersburg, Tampa; babysitting and nanny agencys in Tampa; truck tire services in Tampa; urgent cares in Tampa, Temple Terrace; cinemas in Riverview, Ruskin, Tampa; swim schools in Tampa; aquariums in Tampa; moving companys in Tampa; escape rooms in Tampa; tennis and sports courtss in St. Petersburg; hardware stores in Tampa; thrift stores in Tampa. 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.

{
  "type": "object",
  "properties": {
    "location": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "a 5-digit US postcode, a city (\"Tampa, FL\") or \"lat,lng\". Optional: without it every niche is listed with its totals."
    },
    "radius_miles": {
      "type": "number",
      "minimum": 1,
      "maximum": 250,
      "description": "How far from the location counts as «here». Default 15 (the same in every tool)."
    },
    "detail": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "compact",
            "full"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "compact (default without a matched niche): keys and counts; full: every niche with tags, coverage and conditions"
    },
    "niche": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 80
        },
        {
          "type": "null"
        }
      ],
      "description": "one niche key: that niche in full (tags, coverage, every condition it publishes). Another word returns `variants` with why, never a substitute"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 (1272) · hair salon (599) · dentist (574) · barber (447) · nail salon (430) · auto repair (363) · florist (345) · medical clinic (342) · gas station (334) · massage (321) · oil change (308) · print shop (291) · insurance agent (280) · clothing store (277) · beauty salon (274) · accountant (269) · grocery (261) · bakery (248) · appliance repair (235) · lawyer (230) · pizza (228) · notary (225) · storage (223) · real estate agent (222) · pharmacy (216) · optometrist (215) · hvac (214) · chiropractor (212) · catering (203) · auto parts store (202) · event venue (196) · body shop (188) · bar (187) · pet grooming (186) · jewelry (176) · ev charging station (169) · furniture (165) · electrician (163) · coffee shop (160) · roofer (160) · photographer (159) · hotel (158) · tire shop (156) · daycare (153) · car dealer (150) · tutoring (149) · tattoo studio (147) · pressure washing (145) · veterinarian (145) · movers (143) · landscaping (142) · towing (142) · windows and doors (138) · elder care and home care (135) · pool service (134) · parking (131) · car wash (130) · plumber (128) · truck tire service (126) · fuel delivery (125) · urgent care (123) · liquor store (120) · cleaning (118) · party rental (118) · truck repair (118) · car rental (116) · travel agency (114) · window cleaning (103) · physical therapy (101) · jewelry and watch repair (97) · pest control (97) · wedding planner (95) · music lessons (93) · tree service (93) · locksmith (90) · shipping and packing store (88) · dry cleaner (87) · phone repair (85) · carpet cleaning (84) · dance studio (83) · junk removal (83) · ice cream shop (81) · med spa (77) · septic and well service (76) · auto glass (71) · fishing charter and boat tours (67) · painter (67) · boat rental (62) · handyman (61) · bike repair (59) · garden center and nursery (59) · tailor (51) · pet boarding (50) · dog walking and pet sitting (45) · garage door (44) · mattress (44) · hardware store (41) · yoga (40) · general contractor (39) · driving school (38) · thrift store (31) · pet store (27) · funeral home (26) · medical equipment rental (25) · butcher and seafood market (24) · swim school (20) · bike and jet ski rental (16) · golf course (15) · juice bar (15) · cinema (13) · escape room (11) · kids play center (11) · tennis and sports courts (10) · meal prep (9) · bowling and billiards (8) · motorcycle repair (8) · shooting range (8) · babysitting and nanny agency (7) · specialty grocery and farmers market (6) · brewery (5) · computer repair (4) · kids sports and activities (4) · martial arts (4) · taxi and transfer service (4) · shoe repair (3) · museum (2) · aquarium (1) · butcher (1) · motel (1) · services (1) · transportation service (1); known but not scanned anywhere: candle shop, confectionery, garden center, gift shop, party shop, toy store. 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.

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "a niche key from list_niches, exactly (another word returns the variants to choose from, never a substitute)"
    },
    "location": {
      "type": "string",
      "maxLength": 200,
      "description": "a 5-digit US postcode (best), a city (\"Tampa, FL\") or \"lat,lng\". Required: the shelf is a place."
    },
    "radius_miles": {
      "type": "number",
      "minimum": 1,
      "maximum": 250,
      "description": "Default 15 (the same in every tool)."
    },
    "query": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "chooses which ITEM each card shows («red roses», «balayage»); it does not filter or reorder businesses — for that, search_catalog"
    },
    "needed_by": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ],
      "description": "when: «sunday» / «today» / «2026-11-08» (open that day), «tomorrow 19:00» / «now» (open at that minute), «after 15:00» / «tomorrow after 3pm» (open after then; a free slot only where the source knows slots) — on each business’s own clock; adds `time` {asked_as, day, hours, state, why} and LEAVES OUT only the cards refuted for the way the trade is done (see excluded)"
    },
    "max_price": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "the most for ONE offering, in USD: groups the cards in_budget · budget_unknown · over_budget (nobody is left out) and picks the shown offering inside it (exact, then kind, then partial matches); fixed prices compare; a «from» price above the budget is over, under it budget_unknown"
    },
    "deliver_to": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "where it must be brought (a postcode is best): adds can_deliver_to per card — confirmed when the published area names the place, refuted when the business says no, unknown otherwise"
    },
    "properties": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "min": {
            "type": "number"
          },
          "max": {
            "type": "number"
          },
          "equals": {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          }
        },
        "required": [
          "key"
        ],
        "additionalProperties": false
      },
      "maxItems": 8,
      "description": "facts to read off each card without filtering: property_states {key: \"confirmed <value>\" | \"refuted\" | \"unknown\"}"
    },
    "tags": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "maxItems": 8
        },
        {
          "type": "null"
        }
      ],
      "description": "FILTER by the niche’s own tags, as list_niches gives them («steak house», «italian», «dish»): a card without one of them is left out; the order does not change. Spelling is folded («steakhouse» = «steak house»)."
    },
    "page": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 300
        },
        {
          "type": "null"
        }
      ],
      "description": "the `next_page` token of the previous answer"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "cards per page. Default 10."
    },
    "intent": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "book",
            "order",
            "quote",
            "info",
            "reserve",
            "request_quote",
            "contact",
            "call"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "what the user means to do: shapes the items shown and the ONE action in `next` (book → book / check_slot / call; order → order / quote_order / call; quote → quote_order / call; info → call)"
    },
    "detail": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "task",
            "shelf"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "task (default): the short card under the task; shelf: the older ≤ 1 KB shelf card"
    }
  },
  "required": [
    "niche",
    "location"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "the business name as the user said it"
    },
    "location": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "a postcode, a city or \"lat,lng\" — orders the matches by nearness and bounds the nearby list"
    },
    "radius_miles": {
      "type": "number",
      "minimum": 1,
      "maximum": 250,
      "description": "Default 15 (the same in every tool)."
    },
    "intent": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "book",
            "order",
            "quote",
            "info",
            "reserve",
            "request_quote",
            "contact",
            "call"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "what the user means to do with this business"
    },
    "needed_by": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ],
      "description": "when: «sunday», «tomorrow 19:00», «now», «tomorrow after 15:00» — read on the business’s own clock, three ways (on_day / open_at / slot_after)"
    },
    "query": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "the thing under the task («red roses», «ribeye»): picks the ≤ 5 items on the card"
    },
    "deliver_to": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "description": "where it must be brought (a postcode is best): the card says confirmed / refuted / unknown"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, Brandon, Carrollwood, Gibsonton (+11 more); clothing stores in Apollo Beach, Brandon, Carrollwood, Gibsonton (+3 more); florists in Apollo Beach, Austin, Aventura, Brickell (+21 more); jewelrys in Brandon, St. Petersburg, Tampa; furnitures in Brandon, St. Petersburg, Tampa; nail salons in Apollo Beach, Brandon, Carrollwood, Gibsonton (+6 more); auto parts stores in Lutz, Tampa; jewelry and watch repairs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; hair salons in Apollo Beach, Gibsonton, Greater Northdale, Odessa (+6 more); truck repairs in Tampa; mattresss in St. Petersburg, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; car dealers in Tampa; grocerys in St. Petersburg, Tampa; massages in Apollo Beach, Brandon, Gibsonton, Riverview (+3 more); event venues in Lutz, Riverview, St. Petersburg, Tampa; print shops in Riverview, St. Petersburg, Tampa, Temple Terrace; garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Apollo Beach, Riverview, St. Petersburg, Tampa; spas in Apollo Beach, Riverview, St. Petersburg, Tampa (+1 more); barbers in Apollo Beach, New York, Odessa, Riverview (+4 more); bakerys in St. Petersburg, Tampa, Temple Terrace; auto repairs in St. Petersburg, Tampa, Temple Terrace; music lessonss in St. Petersburg, Tampa; pool services in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; liquor stores in Lutz, Tampa; boat rentals in St. Petersburg, Tampa; tailors in St. Petersburg, Tampa; shooting ranges in Odessa, St. Petersburg, Tampa; butcher and seafood markets in Tampa; unknown trades in Tampa; cafes in Apollo Beach, Riverview, St. Petersburg, Tampa; moverss in Riverview, St. Petersburg, Tampa, Temple Terrace; landscapings in St. Petersburg, Tampa; medical equipment rentals in Gibsonton, Riverview, Tampa; dance studios in Gibsonton, St. Petersburg, Tampa; coffee shops in Chicago, Tampa; plumbers in Apollo Beach, Brandon, Gibsonton, Lutz (+3 more); phone repairs in Apollo Beach, Tampa; medical clinics in Apollo Beach, Riverview, St. Petersburg, Tampa; windows and doorss in Apollo Beach, Tampa; optometrists in Apollo Beach, Riverview, St. Petersburg, Tampa; carpet cleanings in Lutz, St. Petersburg, Tampa; electricians in Apollo Beach, Odessa, Riverview, Ruskin (+2 more); pizzas in Tampa, Temple Terrace; appliance repairs in Apollo Beach, Brandon, Clearwater, Gibsonton (+3 more); roofers in Tampa, Temple Terrace; oil changes in Gibsonton, Riverview, Ruskin, St. Petersburg (+1 more); accountants in Greater Northdale, Lutz, St. Petersburg, Tampa (+1 more); HVACs in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; dentists in Apollo Beach, St. Petersburg, Tampa; barber-shops in Riverview, St. Petersburg, Tampa; car rentals in St. Petersburg, Tampa; chiropractors in Tampa; window cleanings in Apollo Beach, Gibsonton, Riverview, Ruskin (+3 more); wedding planners in Sun City Center, Tampa; med spas in Riverview, Tampa; insurance agents in Greater Northdale, St. Petersburg, Tampa; tattoo studios in Greater Northdale, Ruskin, St. Petersburg, Tampa; hair-salons in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; cleanings in Lutz, Riverview, St. Petersburg, Tampa; meal preps in St. Petersburg, Tampa; caterings in Riverview, St. Petersburg, Tampa, Temple Terrace; photographers in Apollo Beach, Lutz, St. Petersburg, Tampa; elder care and home cares in Tampa; notarys in Gibsonton, Riverview, St. Petersburg, Sun City Center (+1 more); motorcycle repairs in Tampa; travel agencys in St. Petersburg, Tampa; pharmacys in Tampa; locksmiths in Greater Northdale, Riverview, St. Petersburg, Tampa; yogas in Apollo Beach, Ruskin, St. Petersburg, Tampa; storages in Gibsonton, Riverview, Ruskin, Tampa; veterinarians in Lutz, St. Petersburg, Tampa, Thonotosassa; parkings in Ruskin, St. Petersburg, Tampa; ice cream shops in Riverview, Tampa, Temple Terrace; tree services in Odessa, St. Petersburg, Tampa; kids play centers in Brandon, Tampa; handymans in Apollo Beach, Ruskin, St. Petersburg, Tampa; shipping and packing stores in Tampa; driving schools in Tampa, Town 'N' Country; tutorings in Gibsonton, St. Petersburg, Tampa, Westchase; body shops in Tampa; physical therapys in Riverview, St. Petersburg, Tampa; daycares in Apollo Beach, Brandon, St. Petersburg, Tampa; pressure washings in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; cleaning services in Apollo Beach, Gibsonton, Riverview, Ruskin (+2 more); septic and well services in Apollo Beach, Gibsonton, Lutz, Tampa; car washs in Apollo Beach, Riverview, St. Petersburg, Tampa (+1 more); towings in St. Petersburg, Tampa; lawyers in St. Petersburg, Tampa; dog walking and pet sittings in Gibsonton, Lutz, Riverview, Tampa (+1 more); junk removals in Riverview, St. Petersburg, Tampa; dry cleaners in St. Petersburg, Tampa; painters in Kissimmee, St. Petersburg, Tampa; specialty grocery and farmers markets in St. Petersburg, Tampa; pet boardings in Apollo Beach, Tampa; real estate agents in Apollo Beach, St. Petersburg, Tampa, Westchase; auto glasss in Tampa; nail-salons in Tampa; bars in Pine Key, Tampa, Temple Terrace; pest controls in St. Petersburg, Sun City Center, Tampa; general contractors in Apollo Beach, St. Petersburg, Tampa; gas stations in Gibsonton, Riverview, Sun City Center, Tampa; fuel deliverys in Gibsonton, Riverview, Ruskin, Tampa; braids-locss in Tampa; fishing charter and boat tourss in Ruskin, St. Petersburg, Tampa; funeral homes in Tampa; juice bars in Riverview, Tampa; pet stores in Tampa; golf courses in St. Petersburg, Tampa; beauty salons in St. Petersburg, Tampa; servicess in Sunny Isles Beach; bowling and billiardss in St. Petersburg, Tampa; garage doors in Tampa; tire shops in Tampa; taxi and transfer services in Tampa; bike and jet ski rentals in Apollo Beach, Tampa; shoe repairs in Tampa; hotels in St. Petersburg, Tampa; EV charging stations in Tampa; pizzerias in Brooklyn; kids sports and activitiess in St. Petersburg, Tampa; babysitting and nanny agencys in Tampa; truck tire services in Tampa; urgent cares in Tampa, Temple Terrace; cinemas in Riverview, Ruskin, Tampa; swim schools in Tampa; aquariums in Tampa; moving companys in Tampa; escape rooms in Tampa; tennis and sports courtss in St. Petersburg; hardware stores in Tampa; thrift stores in Tampa. 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.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "What the user wants, IN THEIR OWN WORDS AND THEIR OWN LANGUAGE: \"red roses\", \"steakhouse\", \"funeral flowers\", \"movers 2 bedroom\", \"ramo de rosas\", or the same question in a language not written in the Latin alphabet. Matched by MEANING as well as by words, through one multilingual model — so do NOT translate for us and do NOT list synonyms yourself. A place, a date, a budget and a delivery word may be left in (they are parsed out), but the fewer extra words the better the match."
    },
    "location": {
      "type": "string",
      "maxLength": 200,
      "description": "Where the user is, or where it must happen. A 5-DIGIT US POSTCODE IS BEST (\"33139\"): it is the only form a business’s own published delivery or service area can be matched against exactly, so a postcode gets you `how: \"zips\"` and a city name gets you a distance. A city (\"Orlando, FL\") or \"lat,lng\" also work. OPTIONAL IN NAME ONLY — without it nothing is measured and nothing is narrowed, and the answer comes back with `needs` carrying the question to put to your user. \"near me\" is not a location: ask which town."
    },
    "radius_miles": {
      "type": "number",
      "minimum": 1,
      "maximum": 250,
      "description": "How far the business may be, in miles. Default 15."
    },
    "needed_by": {
      "type": "string",
      "maxLength": 60,
      "description": "When it has to happen: \"today\", \"tomorrow\", \"tomorrow 9am\", or an ISO date-time — WITH an offset (2026-10-31T14:00:00-04:00) if you know the user’s zone, because a business whose cut-off is on the RECIPIENT’s clock can only be judged against an offset you give."
    },
    "fulfillment": {
      "type": "string",
      "enum": [
        "delivery",
        "pickup",
        "on_site",
        "at_customer",
        "any"
      ],
      "description": "HOW it must reach the user, and the four are different questions: delivery = brought to the address; pickup = the user collects; on_site = the user goes there (a salon chair, a dining room); at_customer = the business travels (a mover, a plumber). Default any. A business that has not published an answer is KEPT; one that ruled it out is dropped."
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "The most the user will pay for ONE offering, in USD, compared against the lowest number the business published — so \"from $45\" passes \"under $50\". An offering priced on request is NOT filtered out: it comes back `price_type: \"quote_only\"`, because \"they quote it\" is an answer."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "How many BUSINESS CARDS to return. Default 10."
    },
    "properties": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "description": "a property key this index has read — get_card lists the ones established for a niche under `established_properties`, and every card shows its own under `properties`"
          },
          "min": {
            "type": "number",
            "description": "the value must be at least this (a number)"
          },
          "max": {
            "type": "number",
            "description": "the value must be at most this (a number); max 0 = «none»"
          },
          "equals": {
            "type": [
              "string",
              "number",
              "boolean"
            ],
            "description": "the value must be this, as the page wrote it («included», «yes», 8)"
          },
          "exists": {
            "type": "boolean",
            "description": "true = the business must publish this property at all"
          }
        },
        "required": [
          "key"
        ],
        "additionalProperties": false
      },
      "maxItems": 8,
      "description": "THE OPEN LAYER AS A FILTER: facts a business publishes beyond price and availability — a capacity, a deposit, a duration, whether something is included. Three states per key: a published value that fits = confirmed; a published value that does not = refuted (left out, a fact); nothing published = unknown (KEPT, ranked lower, named in the card’s `unknown`). Ask for the user’s real conditions here instead of putting them in `query`: «for 8 people» is {key:\"capacity\",min:8}, «no deposit» is {key:\"deposit\",max:0}."
    },
    "only_independent": {
      "type": "boolean",
      "description": "true = leave out chains (a business whose website serves several of the places found). Default false: a chain is kept as a name, a telephone and a website — it was never read, so it has no offerings — and its card says `chain: true`."
    },
    "only_local": {
      "type": "boolean",
      "description": "true = leave out marketplaces: a business whose shelf names places far from its own address (one local address, hundreds of listings in other cities and countries). Default false: a marketplace is kept, ranked lower, and its card says `marketplace: true` (the full card says why)."
    },
    "detail": {
      "type": "string",
      "enum": [
        "compact",
        "full"
      ],
      "description": "compact (default): the business, its 1–2 best offerings with prices and links, what can be done, and the date it was read — a few hundred bytes a card. full: everything, including images, the sentence each price was read from, variants, all four fulfilment modes with published areas, opening hours and per-field evidence. Ask for full only when the user has chosen a business and you need its delivery area or its hours."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 (60 offerings a page, cheapest first; `offerings_page` says how many there are and the next offset), 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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "the business id from search_catalog"
    },
    "offerings_offset": {
      "type": "integer",
      "minimum": 0,
      "description": "11-05: where this page of offerings starts (default 0); offerings_page.next_offset gives the next one"
    },
    "offerings_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "offerings on this page (default 60, at most 200)"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "the offering id from search_catalog"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "the offering id from search_catalog"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 (60 offerings a page, cheapest first; `offerings_page` says how many there are and the next offset), 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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "the business id from search_catalog"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "offering_id": {
      "type": "string",
      "format": "uuid",
      "description": "the offering id from a card"
    },
    "deliver_to": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 5,
          "maxLength": 200
        },
        {
          "type": "object",
          "properties": {
            "postcode": {
              "type": "string",
              "minLength": 5,
              "maxLength": 10,
              "description": "5-digit US postcode"
            },
            "state": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 40
                },
                {
                  "type": "null"
                }
              ],
              "description": "two letters; read from the postcode when omitted"
            },
            "city": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 80
                },
                {
                  "type": "null"
                }
              ]
            },
            "address_1": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 200
                },
                {
                  "type": "null"
                }
              ],
              "description": "street line, only for the price: some shops price by it"
            },
            "country": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 20
                },
                {
                  "type": "null"
                }
              ],
              "description": "US only for now"
            }
          },
          "required": [
            "postcode"
          ],
          "additionalProperties": false
        }
      ],
      "description": "where it must be brought: \"33139\", \"Miami Beach, FL 33139\", or {postcode, state, city, address_1}"
    },
    "delivery_date": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 40
        },
        {
          "type": "null"
        }
      ],
      "description": "the day the person wants it delivered (\"2026-11-20\"): answered as confirmed only when the shop's cart names that day, else «delivery date: unknown»"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 99,
      "description": "default 1"
    },
    "variant_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 40
        },
        {
          "type": "null"
        }
      ],
      "description": "a variant id from the card when it lists several"
    },
    "options": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "description": "words of the page’s own question, e.g. «card»"
              },
              "value": {
                "type": "string",
                "maxLength": 400,
                "description": "the answer, e.g. «No», or the card message"
              }
            },
            "required": [
              "field",
              "value"
            ],
            "additionalProperties": false
          },
          "maxItems": 10
        },
        {
          "type": "null"
        }
      ],
      "description": "answers to the product page’s own add-on questions; the rest are answered «no»"
    },
    "items": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "offering_id": {
                "type": "string",
                "format": "uuid"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 99
              },
              "variant_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 40
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "options": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "field": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 120
                        },
                        "value": {
                          "type": "string",
                          "maxLength": 400
                        }
                      },
                      "required": [
                        "field",
                        "value"
                      ],
                      "additionalProperties": false
                    },
                    "maxItems": 10
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "offering_id"
            ],
            "additionalProperties": false
          },
          "maxItems": 20
        },
        {
          "type": "null"
        }
      ],
      "description": "several different items of the SAME shop in one cart (delivery and tax on the whole order); offering_id is then the first of them"
    }
  },
  "required": [
    "offering_id",
    "deliver_to"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "format": "uuid",
      "description": "the business id from the card"
    },
    "offering_id": {
      "type": "string",
      "format": "uuid",
      "description": "the offering id from the card"
    },
    "variant_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "description": "the variant (the card lists them when there are several)"
    },
    "quantity": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 999
        },
        {
          "type": "null"
        }
      ],
      "description": "how many — stock is judged against it"
    },
    "from": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ],
      "description": "slots: the window’s start, ISO with an offset"
    },
    "to": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ],
      "description": "slots: the window’s end, ISO with an offset"
    }
  },
  "required": [
    "business_id",
    "offering_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

🔴 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.

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "format": "uuid"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "offering_id": {
            "type": "string",
            "format": "uuid",
            "description": "from the card"
          },
          "variant_id": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 120
              },
              {
                "type": "null"
              }
            ]
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 999,
            "description": "default 1"
          }
        },
        "required": [
          "offering_id"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20
    },
    "customer": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "name": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 120
                },
                {
                  "type": "null"
                }
              ],
              "description": "the buyer’s name (required for a booking)"
            },
            "email": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 200
                },
                {
                  "type": "null"
                }
              ],
              "description": "the buyer’s e-mail: the platform sends the checkout link and the receipt there (for a booking; NOT asked for an order on Shopify or Square, whose checkout asks the buyer)"
            },
            "phone": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 40
                },
                {
                  "type": "null"
                }
              ],
              "description": "the buyer’s telephone with country code"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "only where the platform needs it (WhatsApp); omit for Shopify and Square"
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "a note to the business, in the user’s words (not passed on a Shopify cart link)"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "description": "your own key for this order; reuse it on a retry"
    }
  },
  "required": [
    "business_id",
    "lines"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

🔴 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.

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "format": "uuid"
    },
    "offering_id": {
      "type": "string",
      "format": "uuid",
      "description": "the service, from the card"
    },
    "variant_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "description": "the service variation when the card lists several"
    },
    "start_at": {
      "type": "string",
      "maxLength": 60,
      "description": "ISO date-time with an offset, as check_availability gave it"
    },
    "customer": {
      "type": "object",
      "properties": {
        "name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 120
            },
            {
              "type": "null"
            }
          ],
          "description": "the buyer’s name (required for a booking)"
        },
        "email": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "description": "the buyer’s e-mail: the platform sends the checkout link and the receipt there (for a booking; NOT asked for an order on Shopify or Square, whose checkout asks the buyer)"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 40
            },
            {
              "type": "null"
            }
          ],
          "description": "the buyer’s telephone with country code"
        }
      },
      "additionalProperties": false
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "business_id",
    "offering_id",
    "start_at",
    "customer"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

🔴 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. After it, tell the person it is NOT a booking yet and where the answer will come (`next_steps.tell_the_person`, `next_steps.answer_goes_to`). If you can set reminders, schedule a request_status check (`next_steps.check_again_after` is a pause, not a promised reply time) — and only then say you will check; otherwise tell the person how to ask again. 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.

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "format": "uuid",
      "description": "the business id from the card"
    },
    "what": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200,
      "description": "what the person wants (a service, an item, a table for 4 …)"
    },
    "date": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "YYYY-MM-DD, the business’s local date"
    },
    "time": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "HH:MM, the business’s local time"
    },
    "quantity": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 999
        },
        {
          "type": "null"
        }
      ]
    },
    "branch": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "description": "which location, when the business has several"
    },
    "customer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "contact": {
          "type": "string",
          "minLength": 5,
          "maxLength": 150,
          "description": "e-mail or phone where the owner can answer"
        }
      },
      "required": [
        "name",
        "contact"
      ],
      "additionalProperties": false
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 800
        },
        {
          "type": "null"
        }
      ]
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80,
      "description": "your own key for this request; the same key never makes a second one"
    }
  },
  "required": [
    "business_id",
    "what",
    "customer",
    "idempotency_key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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. `wait_seconds` (optional, default 0 = answer now; at most 45 s are used): waits for the owner and returns as soon as the request is answered or final, otherwise the current status when the wait ends (see `wait.ended`). Waiting is not a promise of an answer, and nothing calls you back afterwards: if it is still waiting, call request_status again later (for example when the person asks). Hanging up does not cancel the request. 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.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "seconds to wait for the owner's answer (0–60, default 0; at most 45 are used)"
    }
  },
  "required": [
    "request_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}