Hostrail Docs

Hostrail is the booking layer for AI agents. Public discovery starts on https://hostrail.dev; canonical human-readable docs live on https://docs.hostrail.dev; typed contracts and protected execution live on https://api.hostrail.dev. Depending on your runtime, cold-start from markdown, capability metadata, or the typed API contract. The core booking flow is four API calls:

POST /v1/search → POST /v1/quotes → POST /v1/holds → POST /v1/bookings

Every response follows the envelope contract — success responses carry data + trace_id + next_actions, and error responses carry a stable error.code + remediation + next_actions so agents can self-recover without human intervention.

For AI agents

Start from the discovery surface your runtime actually uses:

• llms.txt — short machine-readable site index
• llms-full.txt — richer hotel, room-plan, and policy context
• capabilities.json — supported flows, payment methods, and limitations
• coverage.json — live city and hotel rollout status
• Agent Card — machine-readable capabilities and contracts
• OpenAPI spec — full request/response schemas

If your runtime wants public-first discovery through standards metadata, also probe:

• API catalog
• ACP discovery
• OpenID configuration
• OAuth authorization server metadata
• OAuth protected resource metadata

Then read the agent quickstart for a complete cold-start guide.

Key resources:

• MCP server card — transport and capability metadata for https://mcp.hostrail.dev/mcp
• Error catalog — all 44 error codes with remediation
• Booking flow — canonical book_a_room flow with all endpoints

Key concepts

Authentication

Execution is authenticated. Discovery is public.

• Root-site discovery surfaces on hostrail.dev do not require a credential.
• Protected API and MCP calls accept either an operator-managed agent secret (Authorization: Bearer hsk_live_...) or an OAuth access token minted via client_credentials.
• Bookings that act on behalf of a traveler also require a delegation JWT in X-Delegated-User.

See Discovery for the full auth scheme catalog.