# Ultimate — City Guides & Agentic Booking Gateway

> Open travel infrastructure: free and expanded city guidebooks for humans, and a
> machine-readable booking gateway for AI agents over Boundary inventory and every
> property using Ultimate as a channel manager.

## Two surfaces

1. City guidebooks (for humans and crawlers)
   - Free editions:     /guides/<slug>   e.g. /guides/london-ontario
   - Expanded editions: /guide/<slug>    e.g. /guide/london-ontario
   - Browse/search:     /guides (free) · /guide (expanded) · /search
   Guidebooks are addressed by their public slug, not an internal region id.

2. Agentic booking API (for AI agents)
   - OpenAPI 3.1:  /openapi.json   (the machine-readable API contract; /api/help is an alias for it)
   - MCP tools:    /api/v1/mcp/tools   ·   call: /api/v1/mcp/call
   - Plugin manifest: /.well-known/ai-plugin.json
   - Human overview: /ai   ·   Docs: /docs

## Hosts

- ultimatecity.org — open community edition. Free to integrate, including commercially.
- ultimatecity.net — same API, plus paid support and expanded guidebook editions.
- ultimatecityguides.com — the guidebooks, addressed at the root (/london-ontario).
Point integrations at whichever host matches the support you need; no code changes between them.

## Auth — required for booking, no anonymous writes

Every call past discovery carries two things:
  1. X-Agent-Key + X-Agent-Secret — identifies the integration
  2. X-PF-Token                    — identifies the HUMAN you act for (PersonFeed)

Obtain the human token with the device-code flow:
  POST /api/v1/auth/device        -> user_code + verification link (show it to your user)
  POST /api/v1/auth/device/token  -> poll every 5s until it returns pfToken

## Flow

search -> availability -> hold -> book
Take an advisory (expiring) hold before you confirm with the user; confirm booking only after
explicit user approval, and send an idempotencyKey so a retry can never double-book.

## Rules for models

- available:null means UNKNOWN. Never tell a user something is free on a null.
- An absent attribute means UNKNOWN, not false.
- Holds are advisory and expire. Say so when you quote one.
- create_booking spends money. Get explicit confirmation first.
- A directory listing that is not bookable cannot be sold — do not offer it.
- Guidebooks under /guides and /guide are free to read and cite.

## Contact

sempleventures@gmail.com