---
name: tourscanner
description: Search, price and book tours and activities with the TourScanner REST API or its MCP server. Use when a task needs live tours, tickets or experiences worldwide, availability and prices for a date, or the booking lifecycle (hold, pay, confirm, status, cancel, amend).
---

# TourScanner API

One API for about a million tours, tickets and experiences from 14 suppliers.
Base URL `https://tourscanner.ai`. Machine-readable contract: `/openapi.json`.
Reference: `/docs`. Changes: `/changelog`.

## Before you call

- Every request needs an API key in the `X-API-Key` header. Keys are issued by hand: write to api@tourscanner.ai. Without one the API answers 401.
- `https://tourscanner.ai` is production. `POST /api/booking/hold` places a real supplier hold and a real Stripe checkout. Ask for sandbox access before testing a booking.
- Prices are integers in minor units: `3500` is 35.00.

## The booking flow

Call these in order. Do not skip a step.

1. `GET /api/search/destinations?q=rome` returns city ids. `GET /api/search/activities?city=<id>&limit=5` lists activities (use `sort=caliber` for best-ranked first).
2. `POST /api/availability/slots` with `activityId` and `date` returns the live start times and prices. `/api/availability/schedule` only shows which dates are open.
3. `POST /api/booking/options` returns the `productOptionCode` values and the questions the supplier needs answered.
4. `POST /api/booking/hold` reserves the slot and returns `checkoutUrl` and `internalRef`. The traveller pays at `checkoutUrl`; the card is authorised, not charged.
5. `POST /api/booking/confirm` with the Stripe `sessionId` after payment. Keep `internalRef` for status, cancel and amend.

After booking: `/api/booking/status`, `/cancel-quote`, `/cancel`, `/amend-quote`, `/amend`, `/reschedule`, all taking `internalRef`. Quote first, then act: a quote never changes the booking. Only the API key that placed a booking can cancel, amend or reschedule it.

## Rules that prevent mistakes

- Send an `Idempotency-Key` header (a UUID) on hold, confirm, cancel, amend and reschedule. A retry with the same key and body within 24 hours replays the first response; the same key with a different body fails with `IDEMPOTENCY_KEY_REUSED`.
- Errors carry `data.code` and `data.retryable`. Retry only when `retryable` is true. Branch on `data.code`, not on `message`.
- On a 429 wait `Retry-After` seconds. Limits per key per minute: REST 3000; booking status, cancel-quote and amend-quote 600; confirm, cancel, amend and reschedule 120; MCP 120; hosted agent 20.
- Never invent an `activityId`, `productOptionCode` or `internalRef`. Take them from earlier responses.
- A traveller books and pays at the checkout link. Do not collect card details.
- When `bookable` is false (in the slots response or the activity detail) there is no in-house booking: use the `bookingUrl` partner link that comes with it.

## MCP server

The same capabilities are available as a remote MCP server at `https://tourscanner.ai/api/mcp` (Streamable HTTP). Send the key as `Authorization: Bearer <key>` or `X-API-Key`. Tools: `search_destinations`, `search_activities`, `get_activity`, `check_availability`, `get_availability_calendar`, `get_booking_options`, `create_checkout_session`, `get_booking_status`, `get_cancellation_quote`, `cancel_booking`, `get_amendment_quote`, `amend_booking`. Through MCP, `create_checkout_session` returns the checkout link the traveller pays at; cancel and amend run in demo mode.
