Integrator quickstart

Integrate once, access bookable hotel supply.

This lane is for engineers wiring an agent runtime, concierge app or internal tool to Hostrail. Fetch discovery docs first, then move into quote, hold and booking.

Request sandbox access Open docs site

Recommended order

Three fetches before you write code.

Agent Card

https://api.agenthotel.dev/.well-known/agent-card.json

Fetch capability, auth and flow metadata before wiring tools.

OpenAPI

https://api.agenthotel.dev/openapi.json

Fetch request, response and error contracts before code generation or adapters.

Docs site

https://docs.hostrail.dev

Open the canonical quickstart, concept docs and error reference without going through the marketing pages first.

Sandbox

/sandbox

Use the evaluator path when you need a public smoke test before deeper integration.

Discovery

Machine-readable first.

Do not scrape the UI to infer contract details. Use the well-known docs and OpenAPI as the primary integration surfaces.

Development

Credential-scoped local runs.

Use a test agent credential issued from /v1/admin/agents. X-Tenant-Id is only a development hint; runtime auth should be Bearer-first.

Operations

Quote is the live confirmation step.

Markdown and public hotel pages are useful for retrieval, but quote output is the current source of truth for price and cancellation.

Local setup

Bring up the core API first.

The booking surface is contract-driven. Stand up `commerce-api`, seed the catalog, then run reads and quotes before touching mutating flows.

Local commerce-api

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

Local property read

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

First calls

Pull the contract, then create one quote.

Fetch Agent Card

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

Fetch OpenAPI

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

Create quote

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": []
    }
  }'

Assumptions and limits

Integrate against facts, not implied promises.

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 be taken from the typed contract, not inferred from screenshots.

Run MCP server

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"
      }
    }
  }'

Where next

Choose the lane that matches your job.

Access

See sandbox, production and enterprise access lanes before requesting live usage.

Sandbox request

Submit the first sandbox request when you need a reviewed evaluator lane.

Live access

Request production review once the runtime is ready for real booking traffic.

For Agents

Product and runtime framing for agent builders and concierge surfaces.

For Hotels

Supply-side onboarding for hotels that want to register and go live.