Hottub for agents

Hottub: delighting agents and their people. Find businesses, places, groups, radio and web pages, read them as typed data, and act on them with the person's say-so. Free and anonymous; a Search API key adds higher limits and the right to keep results.

Start here

1. Discover. Read /llms.txt, or /.well-known/mcp.json for every server and tool.
2. Ask. GET https://hottub.tech/v1?q=… returns JSON (hottub.search.v1); the MCP tool hottub_search at https://hottub.tech/mcp returns the same.
3. Follow. The answer carries its next steps: place.kinds[].q are ready-made queries, and each entity's service_record_url says what that business can do.

By task

Search API

GET https://hottub.tech/v1. Parameters: q (required, up to 256 characters), scope (all, web, places, videos, news, images or hottub), safe (SafeSearch: strict, moderate or off; moderate when absent, and never remembered), limit (1–25), near (lat,lon), radius_m, min_confidence (0–1), content (1 adds page text to web results), explain (1 adds ranking factors). Unknown parameters are refused, not ignored. Full schema: OpenAPI 3.1.

curl -s 'https://hottub.tech/v1?q=coffee+in+spokane+wa&limit=5'

Operators in q: site:example.com (that site and its subdomains), "exact phrase" and -word. They are read once, sent to the index as structured fields, and echoed in read. lucky=1 (the home page's “I’m feeling spicy”) opens what the page leads with: the first place, the named site, a site's own front page, else the first result. It redirects people's pages only; an agent always gets the answer.

Every results page is also Markdown (&format=md; prefer it to Accept: text/markdown, which a shared cache may answer with HTML) and links its JSON and Markdown forms with <link rel="alternate"> and a Link header.

Reading an answer

place

The place the query names, present only when the Directory found something there: label ("Spokane, WA"), what_label ("Dr. Lee"), city, region, postcode; kinds (each with a ready query q and, for a city, a count; capped means "at least"); highlights (a few of the best places of each kind); whole_q (the query for the whole place).

entities

Hottub Directory businesses and places: entity_id, name, website, phone, address, locality, categories, location (lat, lon), distance_m for ZIP and near reads, confidence, operating_status, service_record_url, thumb (optional: a 320 × 180 preview of the picture the business's own site declares, display only), and provenance (dataset, release, licence, attribution).

site

The site a navigational query names ("costco" → host costco.com, name), present even when none of its pages are in results: go there directly.

results

Documents: kind (web or hottub), url, title, snippet, host, site, site_name, score, published_at (the page's own date, Unix seconds), page content when asked, and facts: what the page states about itself in its markup (kind; price {amount as a decimal string, currency}; availability; rating {value, best, count}; comments). Facts are the page's claims, not Hottub's, and never affect ranking: attribute them to the site when you repeat them.

scope, safe, read

The tab answered, the SafeSearch level, and how the query was read when it carried operators (text, site, phrases, exclude).

results[].video, results[].image

On the videos and images tabs: what the page declares about its video (duration_s, channel, uploaded_at, thumb_url) or its picture (src, width, height, alt). The page's own claims; display only.

news

On the news tab: headlines from Hottub News (title, url, outlet, published_unix, teaser), news reports only and never paid. Link to the story and credit Hottub News; status says when it did not answer.

house

"From Hottub" (kind house): up to two of Hottub's own products (id, name, url, line; an API adds openapi and mcp), only when the query asks for that kind of product ("crm", "api"). Never paid, never among results, and it never changes their order.

sponsored

Paid rows, always labeled, always separate. They never change the order of anything else.

results[].offer

Commerce links, for Search API keys that turned them on and asked with commerce=1: a separate buy link (buy_url, merchant, network, paid_link, disclosure, revenue_share, and price and availability when the page said so) at a merchant with an approved affiliate programme. The result's url stays the clean page address and offers never change which results appear or their order. Show the disclosure beside every buy link (terms).

sources, directory, partial, coverage

A source that did not answer is a status (timeout, unavailable, not_configured), never an empty success, and partial says so. coverage.entities says what the Directory does not cover: abstain rather than read absence as a negative.

How places are read

• City and state: "coffee spokane wa", "pizza in portland or".
• City alone: matched against U.S. Census places. The most populous namesake comes first; when two are close in size ("springfield") both are read, larger first.
• ZIP code: the ZIP's Census centre, within a radius sized to the ZIP; results nearest first, with distance_m.
• Titles: "dr", "doctor" and "physician" read as health care plus the name that follows.
• "Near me": this host never knows where anyone is. Send near=lat,lon from the person's device, with their permission.
• Each place's own page: page_url, at joinhottub.com/places/{name-city-state}--{id} (an id alone, or an older name, redirects there). The same address answers ?format=md and ?format=json.

A place is named only after the Directory finds something there, never from the words alone.

Acting on a result

A business's service record (service_record_url) lists what it accepts. A quote request is prepared with POST https://joinhottub.com/api/directory/v1/actions/prepare under the person's Hottub session; the person reviews exactly what will be shared and approves it; POST /actions then delivers it to the business's inbox, and GET /actions/{id} reports the reply. Nothing is booked or paid on an agent's word: booking_confirmed stays false until the business confirms.

MCP servers

{"mcpServers": {
  "hottub-search":    {"type": "http", "url": "https://hottub.tech/mcp"},
  "hottub-community": {"type": "http", "url": "https://joinhottub.com/api/community/mcp"},
  "hottub-fm":        {"type": "http", "url": "https://hottub.fm/mcp"}
}}

An agent that runs only local servers can use hottubtech mcp from the command-line tool, which forwards to https://hottub.tech/mcp.

Answers sized for agents

• format=json|md|ndjson|text, fields=results.url,results.title and max_tokens=800: one schema, cut to your budget the same way every time (truncated says what went). Sponsored rows never take room from results.
• depth=fast|standard|deep and the hints intent, entity, types, time: we read only what you ask for, so fast answers are faster.
• Every element has an id, kind, source and fetched_at. GET /v1/doc/{id} returns its whole record; POST /v1/batch runs up to 10 queries; stream=1 sends results first.
• Tell us what worked: POST /v1/feedback with the element’s fb token and a verdict (used, helpful, wrong, stale, irrelevant, spam, missing_info, broken_link). Tokens never name the query or you.

Limits and manners

• Search without a key: 60 requests a minute per address across /v1, /mcp and results pages (results pages also 30 a minute on their own), and 50 a day (UTC) per address across /v1, /mcp and results as JSON or Markdown; past it, 429 daily_limit_reached until midnight UTC. A free key gives 2,500 searches a month.
• Directory API: 50 requests per 10 seconds per IP at the edge.
• Every answer sends RateLimit-Policy; a 429 sends Retry-After. Wait, then retry once.
• Need more, or need to keep results? Use a Search API key (Authorization: Bearer hsk_…): limits then belong to your account and plan.
• One request per question a person asked. Branch on status codes and error.code, never on message text.

Trust

• No cookies, no account and no personalisation on this host: everyone gets the same answer, so answers are cacheable and shareable.
• Paid rows appear only in sponsored, labeled. Buy links appear only in results[].offer, opt-in, with their disclosure; a link that already belongs to someone else's affiliate programme is left alone.
• Directory facts are observations, not verification (current_details_verified is false): confirm hours and phone numbers before a person relies on them. Keep provenance.attribution when you show them.
• Web results come from the Hottub web index, built from Common Crawl. Place and ZIP readings use public-domain U.S. Census data.

Discovery

• /llms.txt · /.well-known/mcp.json · /.well-known/agent-service.json · /v1/openapi.json · /opensearch.xml
• Directory API: OpenAPI · developer guide
• Across Hottub: joinhottub.com/llms.txt · joinhottub.com/agents.md · hottub.fm/llms.txt · harmonicbrowser.com/agents.md