# 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://hottub.tech/v1?q=<what the person needs>` for JSON (`hottub.search.v1`), or the MCP tool `hottub_search` at `https://hottub.tech/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 without a key: 60 requests a minute per address across /v1, /mcp and results pages, and 50 a day (UTC) per address across /v1, /mcp and results as JSON or Markdown (`429` `daily_limit_reached` until midnight UTC; a free key gives 2,500 searches a month); every `429` carries `Retry-After`. Branch on status codes and `error.code`, never on message text.

## Keys and prices

Send a Search API key as `Authorization: Bearer hsk_…` (or `X-API-Key`) on `/v1` and `/mcp`. Make keys at https://hottub.tech/account/keys. Limits belong to the account; `/v1/usage` shows this month. Keyed answers carry `terms` and a `storable` flag per result: you may store results and show them later with a link to each source (not rows marked `storable: false`, which came from another provider). Payment never changes the order of results; no query is stored with a key.

- Free: No cost; 2,500 searches a month free; 60 a minute. 2,500 searches a month at no cost. Show “Results from Hottub Search” with a link wherever people see the results.
- Developer: $0.50 per 1,000, then $0.35 at volume; 2,500 searches a month free; 600 a minute. Pay as you go: the first 2,500 searches each month are free, then $0.50 per 1,000. You set a monthly limit on what you spend.
- Scale: $0.50 per 1,000, then $0.35 at volume; 2,500 searches a month free; 1,500 a minute. The same prices with room to grow: $0.50 per 1,000 up to 5 million searches a month and $0.35 per 1,000 after that, with a higher speed limit and spending limit.

Refusals: `429` `rate_limited` / `monthly_limit_reached` / `spend_cap_reached` with `Retry-After`; `401` `key_invalid`; `503` `search_unavailable` (not counted). Price list search-api-2026-10-27.1: https://hottub.tech/developers

Without a key: 60 searches a minute and 50 a day (UTC) per address; past the day, `429` `daily_limit_reached` until midnight UTC. A free key gives 2,500 a month.

## Answers sized for agents

- `format=json|md|ndjson|text`: one schema (`hottub.search.v1`), four shapes. Every element (result, entity, card, answer, correction, suggestion, news, event, sponsored row, `house` row) carries `id`, `kind`, `source`, `fetched_at` and, when feedback is on, `fb`.
- `fields=results.url,results.title,entities.name`: only those (elements keep `id`, `kind`, `fb`; paid rows always keep their label and who paid).
- `max_tokens=800`: the answer is cut to about that many tokens, the same way every time; `truncated` and `truncation` say what went. Sponsored rows never take room from results.
- `depth=fast|standard|deep`: fast reads the index only; standard adds the Directory, events and news where asked; deep reads everything and the first pages' text. Hints `intent`, `entity`, `types`, `time` skip what you did not ask for.
- `GET /v1/doc/{id}`: the whole record or page text for one element. `POST /v1/batch`: up to 10 queries, one budget. `stream=1`: server-sent events, results first, cards as they finish.
- `POST /v1/feedback` `{fb, verdict, note?, url?}`: verdict is used, helpful, wrong, stale, irrelevant, spam, missing_info or broken_link. Tokens name the element, never the query or you.
- Conditional requests (`If-None-Match`) answer `304`; every answer sends `ETag` and `Server-Timing`.
- The same API is served at https://hottub.tech/v1 and https://api.hottubapi.com/v1.

## Commerce links (opt-in, keys only)

- Commerce links (opt-in): when a result is a page at a merchant Hottub has an approved affiliate agreement with, a key that turned Commerce links on gets a separate `offer` object beside the result: `buy_url` (the network's paid link), `merchant`, `network`, `paid_link: true`, `disclosure` and `revenue_share`, plus `price` and `availability` when the page said so. The result's own `url` is always the clean page address, and offers never change which results appear or their order. Show the disclosure beside the link.
- Ask with `commerce=1` on a key that turned it on. Show `disclosure` beside every `buy_url`; terms: https://hottub.tech/terms-for-agents

## API

- [Search API](<https://hottub.tech/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://hottub.tech/v1/openapi.json>): the full schema of the answer and errors
- [MCP server](<https://hottub.tech/mcp>): tool hottub_search, same arguments as the API
- [Command line](<https://hottub.tech/cli>): `curl -fsSL https://hottub.tech/cli/install.sh | sh`, then `hottubtech search <query>` (compact text, `--max-tokens`, `--format jsonl`); `hottubtech mcp` is a stdio MCP server for https://hottub.tech/mcp; `hottubtech help --agent` is the guide
- [Same API, second address](<https://api.hottubapi.com/v1>): keys only on that host
- [MCP discovery](<https://hottub.tech/.well-known/mcp.json>)
- [Agent service record](<https://hottub.tech/.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://hottub.tech/agents>): every task, the answer's fields, places, acting on a result, limits and trust
- [Search API keys and prices](<https://hottub.tech/developers>): plans, limits, keeping results, billing
- [Results as Markdown](<https://hottub.tech/?q=coffee+seattle&format=md>)

## Optional

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