# Hostrail For Developers

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

> Builder quickstart for integrating once and accessing bookable hotel supply.

## Recommended Order

- Fetch the Agent Card before wiring tools or auth.
- Fetch the OpenAPI contract before generating clients or adapters.
- Use the sandbox lane for evaluator-friendly smoke tests before deeper integration.

## First Fetches

- Agent Card: https://api.agenthotel.dev/.well-known/agent-card.json
- OpenAPI: https://api.agenthotel.dev/openapi.json
- Sandbox: https://hostrail.dev/sandbox

## Integration Notes

- Machine-readable surfaces come first; do not infer contracts from the UI.
- Runtime auth should be Bearer-first; tenant headers are only development hints.
- Quote is the live confirmation step for price and cancellation.
- Markdown and hotel pages support retrieval, not final transaction confirmation.

## Local Setup

```bash
cd apps/commerce-api
cp .env.example .env
pnpm db:migrate
pnpm db:seed
pnpm dev
```

## Example Calls

```bash
curl -s 'https://api.agenthotel.dev/.well-known/agent-card.json'
```

```bash
curl -s 'https://api.agenthotel.dev/openapi.json'
```

```bash
curl -s 'https://api.agenthotel.dev/v1/properties' \
  -H 'Authorization: Bearer <hsk_test_or_live_secret>'
```

```bash
curl -s -X POST 'https://api.agenthotel.dev/v1/quotes' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <hsk_test_or_live_secret>' \
  -d '{
    "hotel_id": "<property_id>",
    "room_type_id": "<room_type_id>",
    "rate_plan_id": "<rate_plan_id>",
    "stay": {
      "check_in": "<YYYY-MM-DD>",
      "check_out": "<YYYY-MM-DD>"
    },
    "guests": {
      "adults": 2,
      "children": []
    }
  }'
```

```bash
curl -s -X POST 'https://mcp.hostrail.dev/mcp' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer <hsk_test_or_live_secret>' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "local-probe",
        "version": "0.1.0"
      }
    }
  }'
```

## Assumptions And Limits

- Coverage is limited to onboarded inventory.
- MCP availability depends on environment configuration.
- Hotel descriptions may contain publisher-written marketing language.
- Booking, receipt, and error semantics should come from the typed contract.

## Related Pages

- For Agents: https://hostrail.dev/for-agents
- For Hotels: https://hostrail.dev/for-hotels
- Pricing: https://hostrail.dev/pricing
- Sandbox: https://hostrail.dev/sandbox