{"info":{"name":"TourScanner Tours & Activities API","description":"One API for ~1M tours, tickets and experiences from 14 suppliers: search, live availability, and the full booking lifecycle (hold → pay → confirm → status → cancel / amend) with TourScanner as merchant of record on certified suppliers.\n\n**Auth.** Every endpoint needs an API key, sent as `X-API-Key`. Keys are issued by TourScanner on request: contact api@tourscanner.ai. Without one the API answers 401 `{ \"error\": \"API_KEY_REQUIRED\" }`.\n\n**Retries.** Booking writes accept an `Idempotency-Key` header: a retry with the same key and body replays the original response instead of booking twice.\n\n**Errors** carry `data.code` and `data.retryable`.\n\n**Rate limits.** Counted per API key in a fixed 60-second window. REST API: 3000 requests per minute. Calls that take a booking reference have their own buckets on top of that: `/api/booking/status`, `/cancel-quote` and `/amend-quote` 600 per minute; `/api/booking/confirm`, `/cancel`, `/amend` and `/reschedule` 120 per minute. MCP server: 120 per minute. Hosted agent (`/api/ai/chat` and `/api/ai/chat.json`): 20 per minute. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds); a 429 adds `Retry-After` (seconds) and `data.retryAfterSeconds`.\n\n**Agents.** An MCP server with the same capabilities is at `https://tourscanner.ai/api/mcp` (Streamable HTTP, same API key as `Authorization: Bearer`, `X-API-Key` or `?api_key=`). On the agent layer (MCP and /api/ai/chat), create_checkout_session returns the tourscanner.io checkout link where the traveller books and pays; cancel and amend run in demo mode. Live bookings through your own checkout go through the /api/booking endpoints below.\n\n**Changes.** Dated API changes are at https://tourscanner.ai/changelog.\n\n**Live environment.** This host is production: `/api/booking/hold` places a real supplier hold and a real Stripe checkout. Contact api@tourscanner.ai for sandbox access.\n\nSet the `apiKey` collection variable to your API key. Keys are issued on request: api@tourscanner.ai.","version":"1.0.0","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json"},"auth":{"type":"apikey","apikey":[{"key":"key","value":"X-API-Key","type":"string"},{"key":"value","value":"{{apiKey}}","type":"string"},{"key":"in","value":"header","type":"string"}]},"variable":[{"key":"baseUrl","value":"https://tourscanner.ai"},{"key":"apiKey","value":""}],"item":[{"name":"Search","description":"Destinations and activity catalog","item":[{"name":"Search cities and attractions by name","request":{"method":"GET","header":[],"url":{"raw":"{{baseUrl}}/api/search/destinations?q=rome&lang=en","host":["{{baseUrl}}"],"path":["api","search","destinations"],"query":[{"key":"q","value":"rome","disabled":false,"description":"Free-text search, at least 2 characters (a shorter query returns an empty `results`). Not needed when `id` is given."},{"key":"id","value":"","disabled":true,"description":"City id: look up a single city instead of searching."},{"key":"lang","value":"en","disabled":false,"description":"Language of the returned names, two letters. Default `en`."},{"key":"limit","value":"","disabled":true,"description":"Search mode only. Default 10, capped at 20."}]},"description":"Search cities and attractions by name\n\nFree-text search (`q`) returns matching cities and points of interest in `results`. With `id` (a city id) it instead returns that one city as `destination`, localized to `lang`; `destination` is null when the id is not a city."}},{"name":"Search activities with filters, facets and ranking","request":{"method":"GET","header":[],"url":{"raw":"{{baseUrl}}/api/search/activities?city_name=rome&currency=EUR&lang=en","host":["{{baseUrl}}"],"path":["api","search","activities"],"query":[{"key":"q","value":"","disabled":true,"description":"Free-text search"},{"key":"city","value":"","disabled":true,"description":"City id"},{"key":"city_name","value":"rome","disabled":false,"description":"City name or slug. Older alias of `city`, which also accepts a name."},{"key":"poi","value":"","disabled":true,"description":"Attraction id"},{"key":"tags","value":"","disabled":true,"description":"Comma-separated tag slugs"},{"key":"providers","value":"","disabled":true,"description":"Comma-separated provider ids"},{"key":"bookable_only","value":"","disabled":true,"description":"Pass `1` or `true` to return only activities from providers that can be booked through the booking endpoints."},{"key":"date","value":"","disabled":true,"description":"Only activities available on this date"},{"key":"guide_lang","value":"","disabled":true,"description":"The traveller's language, ISO 639-1 (e.g. it). Tours guided in it rank a little higher on the default sort; nothing is filtered out"},{"key":"min_price","value":"","disabled":true,"description":"Lowest price, in the requested `currency`."},{"key":"max_price","value":"","disabled":true,"description":"Highest price, in the requested `currency`."},{"key":"min_rating","value":"","disabled":true,"description":"Lowest average rating to include."},{"key":"currency","value":"EUR","disabled":false,"description":"Currency of the prices in the response, ISO 4217 code. Default `EUR`."},{"key":"lang","value":"en","disabled":false,"description":"Language of names and descriptions, two letters. Default `en`."},{"key":"lat","value":"","disabled":true,"description":"With lng: only activities within radius_km of this point (e.g. the traveller's location), each with distanceKm. With a city too, the city scope stays and the point narrows it. Invalid coordinates are ignored"},{"key":"lng","value":"","disabled":true,"description":"With lat: see lat"},{"key":"radius_km","value":"","disabled":true,"description":"Search radius around lat/lng in km (default 10, capped at 100)"},{"key":"sort","value":"","disabled":true,"description":"`distance` (nearest first) only with lat/lng. With lat/lng the default `rank` puts nearer activities a little higher"},{"key":"limit","value":"","disabled":true,"description":"Results per page. Default 20, capped at 100."},{"key":"page","value":"","disabled":true,"description":"Page number, starting at 1. Used with `limit`."},{"key":"cursor","value":"","disabled":true,"description":"With `date`: the `nextCursor` of the previous response, to load more."}]},"description":"Search activities with filters, facets and ranking\n\nSearches the activity catalog. Scope it with `city` or `city_name`, `poi`, `tags`, `providers` or a `lat`/`lng` point; narrow with `date`, price and rating filters; order with `sort`. Returns the activities, the total and facets. `limit` defaults to 20 and is capped at 100."}},{"name":"Full activity detail","request":{"method":"GET","header":[],"url":{"raw":"{{baseUrl}}/api/search/product/:id","host":["{{baseUrl}}"],"path":["api","search","product",":id"],"query":[{"key":"lang","value":"","disabled":true,"description":"Language of names and descriptions, two letters. Default `en`."},{"key":"currency","value":"","disabled":true,"description":"Currency of the prices in the response, ISO 4217 code. Default `EUR`."}],"variable":[{"key":"id","value":"100142","description":"Activity id, as returned by the activities search."}]},"description":"Full activity detail\n\nReturns one activity with its description, gallery, itinerary, pricing, features and cancellation policy, in `lang` and `currency`. `reviewsSummary` is null when that language has no generated review digest (there is no English fallback)."}}]},{"name":"Availability","description":"Live slots and prices from suppliers","item":[{"name":"Open dates and prices over a date range","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/availability/schedule","host":["{{baseUrl}}"],"path":["api","availability","schedule"]},"description":"Open dates and prices over a date range\n\nCalendar-level availability between `dateFrom` and `dateTo`. It does not return bookable start times: call /api/availability/slots for a date to get those.","body":{"mode":"raw","raw":"{\n  \"activityId\": 100142,\n  \"dateFrom\": \"2026-12-01\",\n  \"dateTo\": \"2026-12-31\",\n  \"currency\": \"EUR\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Live time slots and prices for one date","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/availability/slots","host":["{{baseUrl}}"],"path":["api","availability","slots"]},"description":"Live time slots and prices for one date\n\nReal-time check with the supplier for one date, returning the bookable start times and prices. The party is read from `adults`, `children`, `youth`, `seniors` and `infants`; with none given it prices 2 adults.","body":{"mode":"raw","raw":"{\n  \"activityId\": 100142,\n  \"date\": \"2026-12-15\",\n  \"adults\": 2,\n  \"currency\": \"EUR\"\n}","options":{"raw":{"language":"json"}}}}}]},{"name":"Booking","description":"Hold, confirm, status, cancel, amend","item":[{"name":"Ticket types, age bands, cancellation policy and booking questions","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/booking/options","host":["{{baseUrl}}"],"path":["api","booking","options"]},"description":"Ticket types, age bands, cancellation policy and booking questions\n\nCall before /api/booking/hold: it lists the product options to choose a `productOptionCode` from, and the questions the supplier needs answered at booking.","body":{"mode":"raw","raw":"{\n  \"activityId\": 100142,\n  \"currency\": \"EUR\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Hold inventory with the supplier and create a Stripe checkout","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Unique per logical request (e.g. a UUID). Retrying with the same key and body replays the first response for 24h; a different body returns 422 IDEMPOTENCY_KEY_REUSED."}],"url":{"raw":"{{baseUrl}}/api/booking/hold","host":["{{baseUrl}}"],"path":["api","booking","hold"]},"description":"Hold inventory with the supplier and create a Stripe checkout\n\nPlaces a real supplier hold on this host. Redirect the traveller to the returned checkoutUrl; call /api/booking/confirm after payment (a Stripe webhook also confirms).","body":{"mode":"raw","raw":"{\n  \"activityId\": 100142,\n  \"date\": \"2026-12-15\",\n  \"startTime\": \"08:30\",\n  \"productOptionCode\": \"15991\",\n  \"adults\": 2,\n  \"contact\": {\n    \"firstName\": \"Ada\",\n    \"lastName\": \"Lovelace\",\n    \"email\": \"ada@example.com\",\n    \"phone\": \"+393331234567\"\n  },\n  \"currency\": \"EUR\",\n  \"lang\": \"en\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Confirm a paid hold with the supplier","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Unique per logical request (e.g. a UUID). Retrying with the same key and body replays the first response for 24h; a different body returns 422 IDEMPOTENCY_KEY_REUSED."}],"url":{"raw":"{{baseUrl}}/api/booking/confirm","host":["{{baseUrl}}"],"path":["api","booking","confirm"]},"description":"Confirm a paid hold with the supplier\n\nTakes the Stripe checkout session id returned on the success redirect and confirms the booking with the supplier once the payment has been made. A Stripe webhook also confirms it.","body":{"mode":"raw","raw":"{\n  \"sessionId\": \"cs_test_a1B2c3D4e5F6g7H8\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Live booking status","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/booking/status","host":["{{baseUrl}}"],"path":["api","booking","status"]},"description":"Live booking status\n\nLooks the booking up by `internalRef` and asks the supplier for its current status. When the supplier cannot be queried it returns the status stored on our side.","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Whether a booking can be cancelled, and the refund","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/booking/cancel-quote","host":["{{baseUrl}}"],"path":["api","booking","cancel-quote"]},"description":"Whether a booking can be cancelled, and the refund\n\nAsks the supplier for a cancellation quote. Read-only: it does not cancel the booking. Call /api/booking/cancel to cancel.","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Cancel a booking with the supplier and refund","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Unique per logical request (e.g. a UUID). Retrying with the same key and body replays the first response for 24h; a different body returns 422 IDEMPOTENCY_KEY_REUSED."}],"url":{"raw":"{{baseUrl}}/api/booking/cancel","host":["{{baseUrl}}"],"path":["api","booking","cancel"]},"description":"Cancel a booking with the supplier and refund\n\nOnly the API key (or account) that placed the booking may call this; anyone else gets 404, the same as an unknown reference. A booking that was never paid can be released by anyone (abandoned checkout).","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\"\n}","options":{"raw":{"language":"json"}}}}},{"name":"Quote a change of date, time, ticket type or party","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/booking/amend-quote","host":["{{baseUrl}}"],"path":["api","booking","amend-quote"]},"description":"Quote a change of date, time, ticket type or party\n\nChecks whether the booking can be changed as requested and returns the price difference with a `quoteRef`. Never changes the booking: pass the `quoteRef` to /api/booking/amend to apply it.","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\",\n  \"changes\": {\n    \"travelDate\": \"2026-12-16\",\n    \"startTime\": \"09:00\"\n  }\n}","options":{"raw":{"language":"json"}}}}},{"name":"Apply a quoted amendment","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Unique per logical request (e.g. a UUID). Retrying with the same key and body replays the first response for 24h; a different body returns 422 IDEMPOTENCY_KEY_REUSED."}],"url":{"raw":"{{baseUrl}}/api/booking/amend","host":["{{baseUrl}}"],"path":["api","booking","amend"]},"description":"Apply a quoted amendment\n\nOnly the API key (or account) that placed the booking may call this; anyone else gets 404, the same as an unknown reference.","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\",\n  \"quoteRef\": \"<quoteRef from amend-quote>\",\n  \"changes\": {\n    \"travelDate\": \"2026-12-16\",\n    \"startTime\": \"09:00\"\n  }\n}","options":{"raw":{"language":"json"}}}}},{"name":"Move a confirmed booking to a new date/time (supported suppliers)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Unique per logical request (e.g. a UUID). Retrying with the same key and body replays the first response for 24h; a different body returns 422 IDEMPOTENCY_KEY_REUSED."}],"url":{"raw":"{{baseUrl}}/api/booking/reschedule","host":["{{baseUrl}}"],"path":["api","booking","reschedule"]},"description":"Move a confirmed booking to a new date/time (supported suppliers)\n\nOnly the API key (or account) that placed the booking may call this; anyone else gets 404, the same as an unknown reference.","body":{"mode":"raw","raw":"{\n  \"internalRef\": \"TS-7-M3F9K2QX-4KD8ZP\",\n  \"date\": \"2026-12-16\",\n  \"startTime\": \"09:00\"\n}","options":{"raw":{"language":"json"}}}}}]},{"name":"Agent","description":"Hosted agent and MCP server","item":[{"name":"Hosted agent turn (non-streaming)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"{{baseUrl}}/api/ai/chat.json","host":["{{baseUrl}}"],"path":["api","ai","chat.json"]},"description":"Hosted agent turn (non-streaming)\n\nRuns one turn of the hosted TourScanner agent over the same tools as the MCP server. Requires an API key. `/api/ai/chat` is the streaming (NDJSON) variant.","body":{"mode":"raw","raw":"{\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What are the best guided tours in Rome?\"\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}}}]}]}