# VistaLink - Full Technical Reference

> This is the extended technical reference for VistaLink's API and MCP server. For a general overview, see [llms.txt](https://vistalink.com/llms.txt).

VistaLink Technologies is a UK-based AI company building multimodal search, direct booking, and voice infrastructure for the hospitality industry. All services are available through MCP (Model Context Protocol) servers and REST APIs for direct integration into AI agents and LLM workflows.

---

## MCP Server

### Connection

The VistaLink MCP server uses HTTP Streamable transport. No npm package required.

```json
{
  "mcpServers": {
    "vistalink": {
      "url": "https://api.vistalink.com/mcp",
      "headers": {
        "Authorization": "Bearer vl_test_..."
      }
    }
  }
}
```

Any MCP-compatible client can connect: Claude, Cursor, custom agents, or any AI platform that supports the Model Context Protocol.

### Protocol Flow

1. **Discover** - Your agent connects and discovers available tools (search_hotels, chat_about_hotels, get_hotel_details, call_hotel).
2. **Invoke** - Your agent calls the appropriate tool with structured input. MCP handles transport and serialization.
3. **Receive** - The server returns structured results directly to your agent. Type-safe, predictable, and ready to use.

---

## MCP Tools

### 1. search_hotels

Search hotels by location, dates, budget, amenities, vibe, hotel name, or original website URL. Returns ranked results with images, guest reviews, room types, pricing, and proximity to landmarks.

#### Input Schema

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | no | City name (e.g., "Paris", "Milan") |
| latitude | float | no | Search center latitude |
| longitude | float | no | Search center longitude |
| radius_meters | integer | no | Search radius in meters |
| check_in | string | no | Check-in date (YYYY-MM-DD) |
| check_out | string | no | Check-out date (YYYY-MM-DD) |
| guests | integer | no | Number of guests |
| rooms | integer | no | Number of rooms |
| budget_min | float | no | Minimum budget per night |
| budget_max | float | no | Maximum budget per night |
| currency | string | no | Currency code (default: EUR) |
| amenities | string | no | Comma-separated amenity codes (e.g., "wifi,pool") |
| vibe | string | no | Comma-separated vibe tags (e.g., "romantic,quiet") |
| limit | integer | no | Max results to return (default: 20, max: 50) |
| hotel_name | string | no | Search by hotel name (partial match) |
| booking_url | string | no | Search by the hotel's original website URL (partial match) |
| include_rates | boolean | no | Fetch live rates from booking sources (adds ~30-45s) |

#### Example Request (tool_use)

```json
{
  "name": "search_hotels",
  "input": {
    "city": "Tokyo",
    "check_in": "2026-04-15",
    "check_out": "2026-04-18",
    "guests": 2,
    "vibe": "modern,design-forward"
  }
}
```

#### Example Response (tool_result)

```json
{
  "hotels": [
    {
      "hotel_id": "htl_9k2mX8vL",
      "name": "The Aoyama Grand Hotel",
      "city": "Tokyo",
      "star_rating": 4.5,
      "review_score": 9.1,
      "thumbnail_url": "https://...",
      "amenities": ["wifi", "pool", "gym"],
      "price": { "min": 180, "max": 320, "currency": "EUR" },
      "images": [{ "url": "https://...", "label": "exterior" }],
      "distance_km": 1.2,
      "review_highlight": "Perfect location, stunning views..."
    }
  ],
  "total": 23,
  "fallback_used": false
}
```

---

### 2. chat_about_hotels

Describe what you want in natural language. The Engine matches on vibe, guest sentiment, and visual aesthetics - returning hotels that genuinely fit. Supports multi-turn sessions for follow-ups and comparisons.

#### Input Schema

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| message | string | yes | The user's message or question about hotels |
| session_id | string | no | Existing session UUID to continue a conversation |
| currency | string | no | Currency code for prices (default: EUR) |

#### Example Request (tool_use)

```json
{
  "name": "chat_about_hotels",
  "input": {
    "message": "Find me a romantic boutique hotel in Paris with a rooftop bar",
    "currency": "EUR"
  }
}
```

#### Example Response (tool_result)

```json
{
  "session_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "message": "I found 3 romantic boutique hotels in Paris...",
  "hotels": [
    {
      "hotel_id": "htl_fr8kP2mL",
      "name": "Hotel Le Marais"
    }
  ],
  "usage": {
    "input_tokens": 245,
    "output_tokens": 180
  }
}
```

---

### 3. get_hotel_details

Full hotel profile - description, photos, guest reviews, room types, amenities, pricing, and proximity to points of interest.

#### Input Schema

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| hotel_id | string | yes | The hotel's unique identifier from search results |
| currency | string | no | Currency code for prices (default: EUR) |

#### Example Request (tool_use)

```json
{
  "name": "get_hotel_details",
  "input": {
    "hotel_id": "htl_9k2mX8vL",
    "currency": "EUR"
  }
}
```

#### Example Response (tool_result)

```json
{
  "hotel_id": "htl_9k2mX8vL",
  "name": "The Aoyama Grand Hotel",
  "description": "A modern luxury hotel in the heart of Shibuya...",
  "city": "Tokyo",
  "star_rating": 4.5,
  "amenities": ["wifi", "pool", "spa"],
  "images": [
    {
      "url": "https://...",
      "category": "exterior"
    }
  ]
}
```

---

### 4. call_hotel

Voice AI agent that calls hotels to negotiate rates, confirm or cancel bookings. Returns a call ID - use the REST endpoints GET /v1/call/{id}/status and GET /v1/call/{id}/results to retrieve transcript, audio recording, and structured outcomes.

#### Input Schema

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| hotel_id | string | yes | The hotel's unique identifier |
| phone_number | string | yes | Phone number in E.164 format (e.g., "+39055123456") |
| hotel_name | string | yes | Name of the hotel to call |
| scenario | string | no | Call scenario (default: "hotel_negotiation") |
| guest_first_name | string | no | Guest first name |
| guest_last_name | string | no | Guest last name |
| check_in_date | string | no | Check-in date (YYYY-MM-DD) |
| check_out_date | string | no | Check-out date (YYYY-MM-DD) |
| number_of_rooms | integer | no | Number of rooms to book |
| number_of_people | integer | no | Number of guests |
| booking_price | float | no | Current booking price to negotiate against |
| room_type | string | no | Room type (e.g., double, suite) |
| currency | string | no | Currency code (default: EUR) |
| language | string | no | Language for the call (default: en) |
| confirmation_number | string | no | Booking confirmation number (for confirm/cancel) |
| special_requests | string | no | Special requests for the hotel |
| caller_instructions | string | no | Free-form instructions for the AI caller |

#### Scenarios

| Scenario | Description |
|----------|-------------|
| hotel_negotiation | Negotiate rates below OTA prices |
| hotel_confirm_booking | Confirm an existing booking |
| hotel_cancel_booking | Cancel a booking |
| restaurant_booking | Book a restaurant reservation |
| restaurant_cancel_booking | Cancel a restaurant reservation |

#### Example Request (tool_use)

```json
{
  "name": "call_hotel",
  "input": {
    "phone_number": "+39055123456",
    "hotel_name": "Hotel & Palazzo",
    "scenario": "hotel_negotiation",
    "check_in_date": "2026-04-15",
    "booking_price": 280,
    "currency": "EUR"
  }
}
```

#### Example Response (tool_result)

```json
{
  "success": true,
  "call_id": "call_7f3kR9mW",
  "status": "in_progress",
  "message": "Call initiated to Hotel & Palazzo"
}
```

---

## MCP Resources

Resources expose read-only data your agent can reference without making tool calls.

| URI | Description |
|-----|-------------|
| `hotel://{hotel_id}` | Full hotel profile as a URI template. Returns name, description, star rating, amenities, images, rooms, pricing, reviews, and location data. All prices in EUR. |
| `amenities://catalog` | Complete list of supported amenity codes with human-readable labels. Use this to validate amenity filters before searching. |

---

## MCP Prompts

Guided prompts that structure complex workflows.

| Prompt | Description |
|--------|-------------|
| `search_wizard` | Generates a structured search plan from natural-language criteria. Accepts destination, dates, budget, guests, star rating, amenities, vibe, point of interest, and free-form preferences. |
| `comparison_template` | Given a list of hotel IDs, produces step-by-step instructions for your agent to fetch details and build a side-by-side comparison table. |

---

## REST API

Base URL: `https://api.vistalink.com`

All REST endpoints require a Bearer token in the Authorization header.

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/chat | AI-powered hotel conversation with session continuity |
| POST | /v1/search | Structured hotel search - fast path, no LLM |
| GET | /v1/hotels/{id} | Full hotel profile with images and rooms |
| POST | /v1/call | Initiate a voice call to a hotel (negotiate, confirm, cancel) |
| GET | /v1/call/{id}/status | Call status, transcript, and audio recording |
| GET | /v1/call/{id}/results | Structured call outcomes (negotiated price, booking status) |
| POST | /v1/guests | Create a guest profile for your users |
| GET | /v1/guests/{id} | Retrieve a guest profile |
| PATCH | /v1/guests/{id} | Update a guest profile |
| DELETE | /v1/guests/{id} | GDPR-compliant data deletion |
| POST | /v1/keys | Generate a new API key |
| GET | /v1/keys | List all API keys for your account |
| DELETE | /v1/keys/{prefix} | Revoke an API key by prefix |
| GET | /v1/usage | Aggregated usage summary for your account |
| GET | /v1/billing/invoices | Invoice history for your account |

### REST Example: POST /v1/chat

Request:
```json
{
  "message": "Find a romantic hotel in Rome near the Colosseum",
  "session_id": null,
  "currency": "EUR",
  "locale": "en"
}
```

Response:
```json
{
  "session_id": "a1b2c3d4-...",
  "message": "Here are 3 romantic hotels near the Colosseum...",
  "hotels": [{ "hotel_id": "htl_...", "name": "..." }],
  "usage": { "input_tokens": 245, "output_tokens": 180 }
}
```

### REST Example: POST /v1/search

Request:
```json
{
  "city": "Milan",
  "check_in": "2026-06-01",
  "check_out": "2026-06-05",
  "budget_max": 200,
  "amenities": ["wifi", "pool"],
  "limit": 10
}
```

Response:
```json
{
  "hotels": [{
    "hotel_id": "htl_...",
    "name": "...",
    "city": "Milan",
    "star_rating": 4,
    "price": { "min": 120, "max": 190 },
    "images": [{ "url": "..." }]
  }],
  "total": 15,
  "fallback_used": false
}
```

---

## Authentication

API keys use the format `vl_test_*` (sandbox) or `vl_live_*` (production).

```bash
curl -X POST https://api.vistalink.com/v1/search \
  -H "Authorization: Bearer vl_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "city": "Paris" }'
```

---

## Response Headers

Every API response includes rate limit and quota headers:

| Header | Description |
|--------|-------------|
| X-RateLimit-Limit | Maximum requests allowed per minute |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
| X-Monthly-Quota-Limit | Monthly request quota for your tier |
| X-Monthly-Quota-Remaining | Requests remaining this billing period |
| X-Monthly-Quota-Reset | ISO 8601 date when the monthly quota resets |

---

## Pricing Tiers

### Free - $0
- 100 calls/month
- Sandbox environment only
- Tools: search_hotels, chat_about_hotels, get_hotel_details

### Pro - Pay-as-you-go
- 120 requests/minute
- Production environment
- REST API access
- Usage analytics
- Pricing per call:
  - search_hotels: $0.01/call
  - get_hotel_details: $0.005/call
  - chat_about_hotels: $0.03/call
  - call_hotel: $0.50 flat (up to 10 min) + $0.05/min overage

### Enterprise - Custom
- Unlimited requests
- Volume discounts
- Custom call pricing
- Dedicated support + SLA

---

## Booking Tools (Coming Soon)

The following tools are in development and will be available as both MCP tools and REST endpoints:

- check_availability
- create_reservation
- get_reservation
- cancel_reservation

---

## Use Cases

- A travel-planning AI agent that searches for hotels conversationally
- An AI concierge that finds and books hotels matching complex preferences
- A developer building an AI travel assistant with real hotel data
- Agentic workflows that autonomously research, compare, and book hotel stays
- Multi-agent systems where a booking agent coordinates with a search agent

---

## Key Facts

- **Founded**: 2025
- **Headquarters**: United Kingdom
- **Properties indexed**: 280,000+ hotels worldwide
- **Reviews analyzed**: 14M+ guest reviews
- **Visual dimensions**: 14 aesthetic and spatial categories per property
- **Image recognition accuracy**: 99%
- **Search response time**: Under 40ms
- **Voice latency**: Under 280ms end-to-end (Caladan)
- **MCP tools**: 4 (search_hotels, chat_about_hotels, get_hotel_details, call_hotel)
- **MCP resources**: 2 (hotel://{hotel_id}, amenities://catalog)
- **MCP prompts**: 2 (search_wizard, comparison_template)
- **REST endpoints**: 15
- **Contact**: contact@vistalink.com
- **Website**: https://vistalink.com
- **Developer docs**: https://vistalink.com/developers
- **Hotel extranet**: https://extranet.vistalink.com