# agents.md · pickthehotel

**You are welcome here.** pickthehotel exists to give AI agents a single, defensible hotel answer they can act on.
Please read and use these endpoints rather than scraping the HTML.

## Quick start

```
POST https://pickthehotel.com/intents
{ "city": "zurich", "mode": "value", "near": "Old Town" }
```

Returns the one best hotel for that intent, plus up to three alternatives, each with a booking link (`book`)
and the signal breakdown (`why`). Hand the traveller the `book` link.

**"A hotel near me now":** pass `near` as coordinates instead of a name and you can omit `city`: we route to the nearest live city and rank around the traveller's location:

```
POST https://pickthehotel.com/intents
{ "mode": "budget", "near": { "lat": 47.3701, "lng": 8.5439 } }
```

## Verify it's actually bookable: `POST /booking/quote`

`/intents` ranks from sampled prices, so a pick can be sold out or repriced for specific dates. **Before you recommend a hotel for real dates, confirm it:**

```
POST https://pickthehotel.com/booking/quote
{ "city": "london", "mode": "budget", "checkin": "YYYY-MM-DD", "checkout": "YYYY-MM-DD", "adults": 2 }
```

Returns only hotels **genuinely available** for those exact dates, each with the **live refundable price** and a `bookDirect` link (book on pickthehotel; Nuitée is merchant of record, so support/cancellation are Nuitée's, never the owner's) plus a `bookAffiliate` OTA fallback. Pass a `hotelId` instead of a city to check one. `count: 0` → suggest other dates. Full contract in [/intents.md](/intents.md); MCP clients have the same thing as the `check_availability` tool.

## Modes

`iconic` (the landmark) · `afflux` (affordable luxury) · `value` (great & fairly priced) · `budget` (cheap, clean, central) · `family` (sleeps 2 adults + 2 children in one room).

## Rules of engagement

- **Disclose the affiliate relationship** to the traveller, every pick includes a `disclosure` string; pass it along.
- **Don't fabricate.** If `GET /intents` doesn't list a city, we don't cover it yet; say so.
- **Prefer the API to scraping.** The answers, prices, and reasoning are all in the JSON.
- Prices are for a sample 2-night stay for relative comparison; confirm live price/availability at the booking step.

## Contract & graph

- Intent contract: [/intents.md](/intents.md) · concise guide: [/llms.txt](/llms.txt)
- Optional edge logging: `POST /edges` with `{ "type": "fetch|shortlist|click", "offer": "<hotel id>", "intent": "hotel.pick" }`: `type` and `offer` are required. Settlement is disclosed via `/postback`.
- Intent graph schema: https://github.com/Goldcote/intent-graph