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, anonymous, no key.

Start here

1. Discover. Read /llms.txt, or /.well-known/mcp.json for every server and tool.
2. Ask. GET https://search.joinhottub.com/v1?q=… returns JSON (hottub.search.v1); the MCP tool hottub_search at https://search.joinhottub.com/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://search.joinhottub.com/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://search.joinhottub.com/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.

sponsored

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

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.

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://search.joinhottub.com/mcp"},
  "hottub-community": {"type": "http", "url": "https://joinhottub.com/api/community/mcp"},
  "hottub-fm":        {"type": "http", "url": "https://hottub.fm/mcp"}
}}

Limits and manners

• Search: 60 requests a minute per client IP across /v1, /mcp and results pages (results pages also 30 a minute on their own).
• 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.
• 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.
• 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