The public surface

Most of kyro.house is a signed-in family's business. What is open is small, documented, and meant to be used by agents as much as by people: event pages and their replies, a calendar file per event, the MCP server for bots the owner has invited, and the discovery files. Everything else answers with a real status code and a JSON problem, never an HTML error page.

Specs and discovery

• /openapi.json — OpenAPI 3.1 for the public routes: operationIds, typed responses, one error model.
• /.well-known/mcp.json — the MCP server (Streamable HTTP at /eve/v1/mcp; bearer tokens are issued only by the household's owner).
• /llms.txt and /llms-full.txt — what this is, when to use it, how to set up your own.
• /sitemap.xml, /robots.txt — the public pages; AI crawlers are welcome on them.

Examples

# an event page's data (public by link)
curl -s https://kyro.house/api/events/<id>

# become a guest: get a code, then trade it for the guest cookie
curl -s -X POST https://kyro.house/api/events/<id>/code \
  -H 'content-type: application/json' -d '{"name":"Pat","email":"pat@example.com"}'
curl -s -c jar -X PUT https://kyro.house/api/events/<id>/code \
  -H 'content-type: application/json' -d '{"email":"pat@example.com","code":"123456"}'

# reply
curl -s -b jar -X POST https://kyro.house/api/events/<id> \
  -H 'content-type: application/json' -d '{"attending":true,"headcount":2,"bringing":"dessert"}'

# the same pages as Markdown
curl -s -H 'Accept: text/markdown' https://kyro.house/info

Errors, versions, limits

• Errors are RFC 9457 problem details (application/problem+json) with a machine-readable code: not_found, unauthorized, gone, bad_request, rate_limited.
• The public API is versioned in the path (/api/*; the eve runtime is /eve/v1/*). A route that is going away carries Deprecation and Sunset headers for at least 90 days and is listed under x-deprecations in the spec first.
• Public routes answer with RateLimit-Limit / RateLimit-Policy (60 requests per minute per IP) and Retry-After on a 429.
• Markdown negotiation: send Accept: text/markdown to any public page and get Markdown with Vary: Accept.

Run your own

The whole system is MIT at github.com/kyleroche/kyrohome; the site agents for LAN devices are in woodhouse-site. Start with the README, then CLAUDE.md. There is no hosted multi-tenant version and no API keys to request — your instance is yours.