H2Home Developer Documentation

H2Home is a premium bottled water delivery subscription service in Atlanta, GA. This page documents the public API surface and the conventions software agents should follow when working with h2home.io.

Machine-readable resources

• OpenAPI 3.0 spec — Machine-readable reference for the H2Home API
• llms.txt — Agent guidance: what H2Home is for and how to call it
• Sitemap — All indexable URLs with lastmod dates

Authentication

Customer endpoints use session cookies issued by better-auth. Sign in at /signin (email/password or Google OAuth); the session cookie authenticates subsequent API requests. Unauthenticated requests to protected endpoints return 401.

Public endpoints

POST /api/contact

Send a message to the H2Home team. Rate limit: 5 requests/minute per IP.

curl -X POST https://www.h2home.io/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","subject":"Delivery zones","message":"Do you deliver to Decatur?"}'

POST /api/funnel

Record an onboarding funnel analytics event. Requires a step field. Rate limit: 60 requests/minute per IP.

curl -X POST https://www.h2home.io/api/funnel \
  -H "Content-Type: application/json" \
  -d '{"step":"select_water_brand","completed":true}'

Rate limiting

API responses include the standard rate limit headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds until the window resets), and RateLimit-Policy (e.g. 5;w=60). When a limit is exceeded the API returns 429 with a Retry-After header — wait that many seconds before retrying.

Markdown content negotiation

Key pages (home, pricing, FAQ, about, contact, blog, and this page) serve markdown when requested with Accept: text/markdown; responses set Vary: Accept. Unknown paths return a real HTTP 404.

curl -H "Accept: text/markdown" https://www.h2home.io/pricing