# Hostrail For Agents

Markdown companion for [https://hostrail.dev/for-agents](https://hostrail.dev/for-agents).

> Runtime integration guidance for Hostrail, the booking layer for AI agents.

## What This Page Covers

- Machine-readable discovery surfaces for agent runtimes.
- The recommended execution path: search, quote, hold, book, then guest service.
- Example REST calls for quote, hold, booking, and receipt verification.
- Operational notes on pricing, cancellation policy, and limited rollout coverage.

## Machine Entry Points

- Agent Card: https://api.agenthotel.dev/.well-known/agent-card.json
- OpenAPI: https://api.agenthotel.dev/openapi.json
- Site index: https://hostrail.dev/llms.txt
- Full site catalog: https://hostrail.dev/llms-full.txt
- Access tiers: https://hostrail.dev/pricing
- Developer quickstart: https://hostrail.dev/for-developers
- Sandbox lane: https://hostrail.dev/sandbox

## Recommended Execution Path

1. Search: retrieve hotel, room-type, and policy context.
2. Quote: confirm current price, taxes, cancellation terms, and expiry.
3. Hold: reserve availability while payment or confirmation is pending.
4. Book: create the booking and persist the booking reference.
5. Service: use guest portal or booking APIs for follow-up actions.

## Reliability Notes

- Quote output is the current source of truth for price and cancellation terms.
- Markdown and hotel descriptions are retrieval aids, not booking confirmation.
- Coverage is limited to onboarded inventory and rollout is incremental.
- MCP availability depends on environment configuration.

## Live Sample Context

- Live property data is temporarily unavailable. Use placeholders below and fetch `/v1/properties` again when the commerce API is reachable.
- Sample property name: unavailable
- Property ID: <property_id>
- Room type ID: <room_type_id>
- Rate plan ID: <rate_plan_id>

## Example Calls

```bash
curl -s 'https://api.agenthotel.dev/v1/properties' \
  -H 'accept: application/json'
```

```bash
curl -s -X POST 'https://api.agenthotel.dev/v1/quotes' \
  -H 'content-type: application/json' \
  -d '{
    "hotel_id": "<property_id>",
    "room_type_id": "<room_type_id>",
    "rate_plan_id": "<rate_plan_id>",
    "check_in": "2026-05-02",
    "check_out": "2026-05-04",
    "adults": 2
  }'
```

```bash
curl -s -X POST 'https://api.agenthotel.dev/v1/holds' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: hold-demo-001' \
  -d '{ "quote_id": "<quote_id>" }'
```

```bash
curl -s -X POST 'https://api.agenthotel.dev/v1/bookings' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: booking-demo-001' \
  -d '{
    "quote_id": "<quote_id>",
    "hold_id": "<hold_id>",
    "payment_intent_id": "<payment_intent_id>",
    "guest": {
      "full_name": "Alex Nguyen",
      "email": "alex@example.com",
      "phone": "+84900111222"
    }
  }'
```

```bash
curl -s -X POST 'https://api.agenthotel.dev/v1/receipts/verify' \
  -H 'content-type: application/json' \
  -d '{ "receipt": <receipt_from_booking_response> }'
```