Hostrail Docs
Canonical docs for the booking layer for AI agents. Start from machine-readable discovery, then search, quote, hold, and book hotel inventory through one system.
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/bookingsEvery 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.
Hostrail also has a human operator surface: hotel-portal. Hotel teams use it
to sign in, choose an organization, complete onboarding, configure PMS/imports,
and prepare supply for live booking.
For hotel operators
If you are a hotel operator or company/chain team using the product directly, start here:
- Hotel Operator Quickstart
- How to use hotel-portal
- Managing multiple organizations
- How to onboard the next property
- How to use Ask AI in hotel-portal
- How to prepare rooms and rates
- How to load inventory safely
- How to review PMS readiness and blockers
- Troubleshooting sign-in and access
- Understanding readiness states and blocker cards
- Hotel Portal FAQ
- Register
- Sign in
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 49 platform error codes with remediation
- Booking flow — canonical
book_a_roomflow with all endpoints
Key concepts
Hotel Operator Quickstart
Start using hotel-portal as a hotel operator without developer setup.
How to use hotel-portal
Sign in, choose an organization, onboard properties, then prepare supply for go-live.
Managing multiple organizations
Understand how one operator account can work across more than one organization.
Use Ask AI
Learn when to rely on Ask AI and when to trust the live portal state instead.
Prepare rooms and rates
Build a clean sellable room catalog before inventory and go-live work begins.
Load inventory safely
Import or review availability without creating avoidable readiness problems.
Troubleshoot sign-in and access
Recover from common operator sign-in and organization access confusion quickly.
Hotel Portal FAQ
Quick answers to common operator questions without reading every guide first.
Envelope contract
Every response follows the same shape. Match on error.code, follow next_actions.
Discovery
Agent Card, OpenAPI spec, error catalog — everything an agent needs to cold-start.
Error model
49 platform error codes with remediation and recovery actions. Agents never guess.
Idempotency
Holds and bookings are idempotent. Retries are safe — even failed payments are sealed.
Authentication
Execution is authenticated. Discovery is public.
- Root-site discovery surfaces on
hostrail.devdo 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 viaclient_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.