API Documentation

Full REST API for searching, checking availability, and booking tours and activities. All responses are JSON. No authentication is required for sandbox testing.

Base URL

http://localhost:3017

Format

JSON

Auth (Sandbox)

None required

Sandbox vs Production
Sandbox is open and free — test the full booking flow with no real charges. For production access with live provider inventory, contact us.

Booking Workflow

The typical integration follows this flow:

Find cities & activities

Availability

Check dates & time slots

Hold & Pay

Reserve + Stripe checkout

Confirm

Finalize booking

GET/api/search/destinations

Search for cities and destinations by name.

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query (min 2 chars)
`lang`	string	No	Language code (default: en)
`limit`	number	No	Max results (default: 10, max: 20)

SandboxTry it

lang

GET/api/search/activities

Search activities by text, city, or filters. Returns paginated results with pricing.

Parameters

Name	Type	Required	Description
`q`	string	No	Full-text search query
`city`	number	No	City ID (from destinations search)
`city_name`	string	No	City name (resolved to ID via full-text search, e.g. "rome")
`sort`	string	No	caliber (default), rating, reviews
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20, max: 100)
`lang`	string	No	Language code (default: en)
`providers`	string	No	Comma-separated provider IDs (2=Tiqets, 3=Viator, 7=Headout)
`min_rating`	number	No	Minimum review rating

SandboxTry it

city_name

city

providers

sort

limit

GET/api/search/product/:id

Get full product detail including description, gallery, itinerary, pricing, features, and cancellation policy.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Activity ID (URL param)
`lang`	string	No	Language code (default: en)

SandboxTry it

POST/api/availability/schedule

Get a monthly availability calendar. Returns which dates have available slots.

Body Parameters

Name	Type	Required	Description
`activityId`	number	Yes	Activity ID
`dateFrom`	string	Yes	Start date (YYYY-MM-DD)
`dateTo`	string	Yes	End date (YYYY-MM-DD)
`currency`	string	No	Currency code (default: EUR)

SandboxTry it

activityId

dateFrom

dateTo

currency

POST/api/availability/slots

Get real-time bookable time slots for a specific date. Use after the user selects a date from the schedule.

Body Parameters

Name	Type	Required	Description
`activityId`	number	Yes	Activity ID
`date`	string	Yes	Date (YYYY-MM-DD)
`adults`	number	No	Number of adults (default: 2)
`children`	number	No	Number of children (default: 0)
`currency`	string	No	Currency code (default: EUR)

SandboxTry it

activityId

date

adults

children

POST/api/booking/options

Get booking form fields: product variants, age bands, booking questions, language guides, and cancellation policy.

Body Parameters

Name	Type	Required	Description
`activityId`	number	Yes	Activity ID
`currency`	string	No	Currency code (default: EUR)
`productOptionCode`	string	No	Specific variant code (returns all if omitted)

SandboxTry it

activityId

currency

POST/api/booking/hold

Hold a booking and create a Stripe Checkout session. Returns a checkoutUrl to redirect the customer to Stripe for payment. The hold uses manual capture — the card is authorized but not charged until the booking is confirmed with the provider.

Body Parameters

Name	Type	Required	Description
`activityId`	number	Yes	Activity ID
`date`	string	Yes	Travel date (YYYY-MM-DD)
`startTime`	string	No	Time slot (HH:MM) or omit for ON_DEMAND
`productOptionCode`	string	Yes	Product variant code (from booking/options)
`passengers`	object	Yes	`{ adults: number, children?: number }`
`contact`	object	Yes	`{ firstName, lastName, email, phone }`
`travelers`	array	No	Traveler details per person
`bookingAnswers`	array	No	Answers to booking questions
`languageGuide`	object	No	Selected language guide
`currency`	string	No	Currency (default: EUR)

Response

{
  "checkoutUrl": "https://checkout.stripe.com/...",
  "internalRef": "TS-3-abc123-def456",
  "expiresAt": "2026-04-10T15:30:00Z",
  "retailPrice": 5400,
  "currency": "EUR"
}

SandboxTry it

activityId

date

startTime

productOptionCode

passengers.adults

contact.firstName

contact.lastName

contact.email

contact.phone

POST/api/booking/confirm

Confirm a booking after Stripe payment. Call this with the session_id from the Stripe success redirect. This captures the payment and confirms with the provider.

Body Parameters

Name	Type	Required	Description
`sessionId`	string	Yes	Stripe Checkout session ID (from success URL query param)

Response

{
  "status": "confirmed",
  "internalRef": "TS-3-abc123-def456",
  "providerRef": "BR-12345678",
  "voucherUrl": "https://...",
  "ticketUrl": "https://...",
  "activityName": "Colosseum Skip-the-Line Tour",
  "travelDate": "2026-05-15"
}

SandboxTry it

sessionId

POST/api/booking/status

Check the current status of a booking.

Body Parameters

Name	Type	Required	Description
`internalRef`	string	Yes	Internal booking reference (e.g. TS-3-abc123-def456)

SandboxTry it

internalRef

POST/api/booking/cancel

Cancel a booking. Cancels with the provider and refunds the Stripe payment.

Body Parameters

Name	Type	Required	Description
`internalRef`	string	Yes	Internal booking reference

SandboxTry it

internalRef

Stripe Payment Flow

The booking system uses Stripe's manual capture mode for safe payment handling:

Hold — POST /api/booking/hold creates a Stripe Checkout session with capture_method: manual. The customer's card is authorized but not charged.
Redirect — Redirect the customer to the returned checkoutUrl. Stripe handles card input securely.
Success callback — After payment, Stripe redirects to your success URL with ?session_id=....
Confirm — Call POST /api/booking/confirm with the session ID. This confirms with the provider, then captures the payment.
Failure — If the provider rejects the booking, the payment authorization is cancelled automatically (no charge).

30-minute expiry
Stripe sessions expire after 30 minutes. If the customer doesn't complete payment in time, the hold is released.

MCP Server

This API is available as a Model Context Protocol (MCP) server, allowing AI agents (Claude, GPT, etc.) to search, check availability, and book activities programmatically.

Configuration

Add the following to your MCP client config (e.g. claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "tours-api": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "http://localhost:3017/api/mcp"]
    }
  }
}

Available Tools

Tool	Description
`search_cities`	Search for cities by name. Params: `query`, `lang`
`search_activities`	Search activities by city name or text query. Params: `city_name`, `query`, `providers`, `sort`, `limit`
`get_product`	Get full product detail. Params: `activity_id`, `lang`
`check_availability`	Get available dates and time slots. Params: `activity_id`, `date_from`, `date_to`
`get_slots`	Get bookable time slots for a date. Params: `activity_id`, `date`, `adults`
`get_booking_options`	Get booking form fields (variants, questions). Params: `activity_id`
`hold_booking`	Hold a booking and get Stripe checkout URL. Params: `activity_id`, `date`, `start_time`, `product_option_code`, `adults`, `contact`
`confirm_booking`	Confirm after Stripe payment. Params: `session_id`
`booking_status`	Check booking status. Params: `internal_ref`
`cancel_booking`	Cancel a booking. Params: `internal_ref`

Example Agent Prompt

"Find skip-the-line tours in Rome for 2 adults on April 20th.
Check availability and show me the best options with prices."

Sandbox by default
The MCP server runs in sandbox mode. All bookings are test-only. For production MCP access, contact us.

Response Codes

Code	Meaning
`200`	Success
`400`	Bad request — missing or invalid parameters
`404`	Resource not found
`422`	Unprocessable — provider error or business logic failure
`500`	Internal server error