API Reference
Reference for Hostrail discovery and booking endpoints, generated from the current OpenAPI 3.1 specification.
Base URLs
| Environment | URL |
|---|---|
| Root site | https://hostrail.dev |
| Docs | https://docs.hostrail.dev |
| Production | https://api.hostrail.dev |
| MCP | https://mcp.hostrail.dev/mcp |
| ACP discovery | https://hostrail.dev/.well-known/acp.json |
| Local | http://localhost:4000 |
Root-site machine surfaces
Before calling protected booking routes, many runtimes should fetch one or more
of the public machine surfaces on hostrail.dev:
/llms.txt— short machine-readable index/llms-full.txt— richer factual catalog/capabilities.json— supported flows, payment methods, and platform limitations/coverage.json— live hotel and city rollout status
Authentication
- Public discovery on
hostrail.devis unauthenticated. - Protected API calls require
Authorization: Bearer <key>andX-Tenant-Id. - The bearer can be an operator-managed
hsk_live_*/hsk_test_*secret or an OAuth access token minted viaclient_credentials.
Endpoint groups
- Discovery —
llms.txt,llms-full.txt, capabilities, coverage, Agent Card, AI plugin, API catalog, OAuth metadata, error catalog, delegation issuers - Supply — List properties, get property details, search availability
- Commerce — Quotes, holds, bookings, cancellations, receipts, checkout
- Guest Portal — Magic link, self-service booking management
- Admin — Inventory, agents, webhooks, delegation issuers, AI config, KPIs
ACP discovery
The platform also publishes ACP discovery metadata:
- Root origin:
https://hostrail.dev/.well-known/acp.json - API origin:
https://api.hostrail.dev/.well-known/acp.json
Current ACP services are deliberately limited to the platform capabilities that already exist:
catalogpricingreservationbooking
Treat ACP as a capability index, not as a promise of a second ACP-native checkout protocol beyond the existing REST and MCP execution lanes.
OpenAPI specification
- JSON:
/openapi.json - YAML:
/openapi.yaml
Use the OpenAPI contract for exact request and response shapes. Use the docs site for quickstarts, concepts, and recovery behavior.
Property & room-type response shapes
Three response shapes exist for properties. Pick the narrowest that covers your use case.
| Shape | Returned by | Room-type detail |
|---|---|---|
PropertyOut | GET /v1/properties (list) | — |
PropertyDetailOut | GET /v1/properties/{id} | room_types[] with full RoomTypeOut |
PropertyFullOut | GET /v1/properties/{id}?full=true | room_types[] plus property-level enrichment |
PropertyOut (list)
id, slug, name, description, star_rating, address, geo, default_currency, timezone.
PropertyFullOut adds
| Field | Type | Notes |
|---|---|---|
amenities | string[] | Property-level amenity codes |
images | string[] | Absolute URLs |
phone | string | null | E.164 when known |
email | string | null | Contact inbox, not guest-facing |
pets_allowed | boolean | |
number_of_rooms | number | null | Total sellable rooms on property |
checkin_time / checkout_time | string | null | Local time, HH:mm |
policies[] | object | Cancellation/child policy versions attached to the property |
RoomTypeOut
In addition to id, code, name, max_occupancy, default_inventory, rate_plans[], each room type now carries:
| Field | Type | Notes |
|---|---|---|
description | string | null | Marketing-ready prose |
bed_type | string | null | e.g. "king", "twin" — unconstrained string for now |
floor_size_sqm | number | null | Square metres |
amenities | string[] | Room-level amenity codes |
images | string[] | Absolute URLs |
smoking_allowed | boolean |
All additions are nullable or defaulted — existing agents that ignore unknown fields continue to work without changes.