# Hottub Search

> Hottub: delighting agents and their people. Search Hottub Directory businesses and places that offer services (with address, phone, website, provenance and licence), web documents from the Hottub web index (built from Common Crawl) and Hottub community content, in one typed answer. Free, no account, no key. Paid rows appear only in `sponsored`, always labeled, and never change organic order.

Call `GET https://search.joinhottub.com/v1?q=<what the person needs>` for JSON (`hottub.search.v1`), or the MCP tool `hottub_search` at `https://search.joinhottub.com/mcp` (streamable HTTP, no auth). Results pages are Markdown with `&format=md` (prefer it to `Accept: text/markdown`, which a shared cache may answer with HTML).

Answer shape: `entities` (Directory records: name, website, address, phone, categories, hours, confidence, provenance.license), `results` (documents: kind `web` or `hottub`, url, title, snippet, host, site), `sponsored` (labeled, separate), `sources` and `directory` (per-source status), `coverage.entities`, `partial`. A source that did not answer is a status, never an empty success; abstain rather than read absence as a negative.

Limits: 60 requests a minute per client IP across /v1, /mcp and results pages; `429` carries `Retry-After`. Branch on status codes and `error.code`, never on message text.

## API

- [Search API](<https://search.joinhottub.com/v1?q=coffee+seattle>): GET, parameters q, scope (all|web|places|videos|news|images|hottub), safe (strict|moderate|off; moderate by default), limit (1-25), near (lat,lon), radius_m, min_confidence. Operators in q: site:example.com, "exact phrase", -word (echoed in `read`)
- [OpenAPI 3.1](<https://search.joinhottub.com/v1/openapi.json>): the full schema of the answer and errors
- [MCP server](<https://search.joinhottub.com/mcp>): tool hottub_search, same arguments as the API
- [MCP discovery](<https://search.joinhottub.com/.well-known/mcp.json>)
- [Agent service record](<https://search.joinhottub.com/.well-known/agent-service.json>)

Places: "coffee spokane wa", a city alone (U.S. Census places; larger namesake first), a ZIP code (nearest first, `distance_m`) or "dr lee spokane" (health care plus the name). `place` names the place only when the Directory found something there, with `kinds` (ready queries, counts) and `highlights`. "Near me" needs `near=lat,lon` from the person's device; this host never knows where anyone is.

## Across Hottub

- [Directory API](<https://joinhottub.com/api/directory/v1/openapi.json>): one business's record and service record; quote requests the person approves
- [Community index](<https://joinhottub.com/api/community/v1>): Hottubs, Soaks and places; MCP `hottub-community` at https://joinhottub.com/api/community/mcp
- [Hottub FM](<https://hottub.fm/llms.txt>): radio stations and what is playing; MCP `hottub-fm` at https://hottub.fm/mcp
- [Hottub](<https://joinhottub.com/llms.txt>): the community behind the Directory

## Docs

- [For agents](<https://search.joinhottub.com/agents>): every task, the answer's fields, places, acting on a result, limits and trust
- [Results as Markdown](<https://search.joinhottub.com/?q=coffee+seattle&format=md>)

## Optional

- [Hottub](<https://joinhottub.com/>): the community behind the Directory
- [Terms](<https://joinhottub.com/terms>)