Hotel data,
built for agents.

A search engine that understands hotels the way humans do - through visual aesthetics, guest sentiment from 18.4M reviews, and 14 dimensions of spatial signal - plus a proprietary voice infrastructure that can call a property and book on the guest’s behalf.

Two interfaces, identical capability: an HTTP-Streamable MCP server at api.vistalink.com/mcp that auto-discovers four tools, two read-only resources (hotel://, amenities://catalog), and two prompt templates in any MCP-compatible client; and a REST API at api.vistalink.com with the same shapes for traditional backends.

Up and running in five minutes.

1. 01

   Create a key

   Sign in with GitHub or email. Generate vl_test_* for the sandbox or vl_live_* for production. Keys are shown once - store in VISTALINK_API_KEY or a secret manager. Rotate and revoke from the dashboard.

2. 02

   Pick a transport

   MCP for agents (Claude, Cursor, custom). REST for any HTTP client. Both expose the same four tools with the same response shapes.

3. 03

   Fire the first request

   The simplest possible call - a chat query with no structured filters - returns a ranked list of hotels with session_id for follow-ups.

4. 04

   Promote to live

   Swap vl_test_ for vl_live_, attach a card on the Pro tier, and you are at 120 req/min with full booking access.

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

Bearer tokens, scoped narrowly.

Every request carries an Authorization: Bearer vl_* header. Test keys (vl_test_*) hit a sandboxed dataset of 5,000 hotels. Live keys (vl_live_*) hit the full 350,820-property index.

• One key, one tenant. Generate as many keys as you need - separate ones per project, environment, or deployment.
• Keys are shown once at creation. Store them in a secret manager or env var; you can revoke and rotate from the dashboard.
• Per-key rate limits, per-key usage, and per-key revocation. Live and test keys can coexist on the same account.
• Keys never appear in URLs - only in the Authorization header. Treat them like passwords.

Free to start. Linear to scale.

Headers on every response: X-RateLimit-Remaining, X-Monthly-Quota-Remaining, X-RateLimit-Reset. Treat 429 as a signal, not a failure.

Wired into any agent.

VistaLink ships an HTTP-Streamable MCP server - no npm package, no local proxy. Drop the URL and a Bearer token into Claude Desktop, Cursor, or any MCP-compatible client and tools, resources, and prompts auto-discover.

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

Four tools. Everything you need.

Read-only URIs, fetchable.

The MCP server also exposes two read-only resources. Use these when your client prefers URI fetches over tool calls (e.g. to cache hotel profiles or validate amenity codes).

Returns the same payload as get_hotel_details for a specific hotel. Fetch by URI without paying for a tool call when your agent has already retrieved the hotel once and just wants a re-read.

Canonical list of amenity codes recognized by search_hotels. Misspelled codes are silently dropped, so validate user-provided amenity language (“hot tub”, “WiFi”, “kid friendly”) against this catalog before passing it in.

Templates for common flows.

The server also exposes prompt templates that codify recurring agent patterns. Invoke via your MCP client’s prompt loader.

Walks an agent through gathering the information needed for a high-quality search_hotels or chat_about_hotelscall. Useful when the user’s first message is ambiguous and you want focused follow-ups before querying.

Renders a structured comparison brief - the agent fetches get_hotel_details for two or more hotels and presents a side-by-side table covering price, location, amenities, reviews, and recommended fit.

The whole spec, one paste.

Drop this file into Claude Projects, the system prompt of a custom agent, Cursor’s .cursorrules, or anywhere else you brief an LLM. It encodes every tool, parameter, routing rule, error code, and pricing line your agent needs to integrate VistaLink without a single round trip to documentation.

# VistaLink API - LLM Integration Brief

Version v1 - Last updated 2026-05-20

VistaLink is a hotel intelligence API for AI agents. 350,820 properties
indexed across visual aesthetics (47.2M analyzed photos), semantic guest
review analysis (18.4M reviews, 18.7M extracted vibe signals), and
contextual matching. Available as an MCP server and a REST API at
https://api.vistalink.com.

> This file is a drop-in system-prompt brief. Paste it into your agent's
> system prompt, Claude Project, Cursor `.cursorrules`, or any other
> place you brief an LLM. It encodes every tool, parameter, error code,
> and gotcha needed to integrate VistaLink without round trips to docs.

---

## Authentication

Every request carries a Bearer token:

```

            ...   

When to call which tool.

The VistaLink API is only for hotel accommodation. Do not route destination advice, flights, restaurants, or general travel questions to the API - handle those locally with your base model. Below is the routing tree we recommend in the system prompt.

User message
  |
  |-- Finding / searching hotels?
  |     |-- Simple criteria (city + dates / budget / amenities) -----> search_hotels
  |     |
  |     |-- Complex (proximity to POI, vibe, reviews, follow-up) ---> chat_about_hotels
  |
  |-- Specific hotel already shown? ---------------------------------> get_hotel_details
  |
  |-- User wants to phone a hotel? ----------------------------------> call_hotel
  |
  |-- Anything else (greetings, travel advice, non-hotel) -----------> Handle locally

Every parameter, every type.

Each tool below ships with a one-click Copy for LLM button - the markdown reference is self-contained: when to use it, every parameter, an example request, an example response, error modes, gotchas. Paste a single tool into your agent’s system prompt without dragging the rest of the spec along.

Structured hotel search. Fast (< 40ms), cheap, no LLM. Returns ranked summary cards with basic info, ratings, pricing.

Response shape:

LLM-powered conversational search. Understands nuance (“a cozy place near the beach that feels like home”), comparisons, and follow-ups. Pass everything you know about the user in context; reuse session_id for multi-turn. Supply user_locationon “near me” queries to skip the GPS-collection round-trip.

Example context payload:

{
  "travel_style": "luxury",
  "purpose": "honeymoon",
  "loyalty_programs": ["Marriott Bonvoy"],
  "dietary": "vegetarian",
  "accessibility": "wheelchair",
  "past_stays": ["Aman Tokyo", "Four Seasons Bali"],
  "preferred_amenities": ["spa", "pool", "room service"],
  "budget_tendency": "splurge on location, save on extras"
}

Clarification protocol. When the engine needs the user to choose between a few interpretations before continuing, the response carries a clarification_pending object. Echo clarification_id and either clarification_option_id or a free-text message on the next call to resolve it.

{
  "session_id": "5b3e...",
  "message": "I need a quick clarification before searching.",
  "hotels": [],
  "clarification_pending": {
    "clarification_id": "c-abc123",
    "question": "Which venue are you closest to?",
    "options": [
      { "id": "ryman",   "label": "Ryman Auditorium",  "description": "Downtown" },
      { "id": "opry",    "label": "Grand Ole Opry",    "description": "17 km from downtown" },
      { "id": "bluebird","label": "The Bluebird Cafe", "description": "11 km from downtown" }
    ],
    "context_hint": "Computing routes to all three would be slow.",
    "allow_free_text": true,
    "display_mode": "inline"
  }
}

Response shape — all fields:

Enriched HotelCard fields:

Example response:

{
  "session_id": "5b3e9f2a-...",
  "message": "Here's the top match for a romantic boutique Paris hotel with a rooftop bar:",
  "hotels": [
    {
      "hotel_id": "a1b2c3d4-...",
      "name": "Hotel Le Marais",
      "city": "Paris",
      "country": "France",
      "star_rating": 4.0,
      "review_score": 9.1,
      "review_count": 1284,
      "amenities": ["wifi", "rooftop", "spa"],
      "price": { "min": 240, "max": 320, "currency": "EUR" },
      "images": [{ "url": "https://...", "label": "exterior" }],
      "hero_image_url": "https://...",
      "hero_image_label": "exterior",
      "explanation": "Top boutique match in the Marais — rooftop bar, excellent reviews (9.1), 240 EUR/night within budget.",
      "explanation_factors": [
        { "factor_type": "review", "human_readable": "Excellent reviews (9.1/10)", "contribution": 0.45 },
        { "factor_type": "amenity", "human_readable": "Rooftop bar", "contribution": 0.30 },
        { "factor_type": "semantic", "human_readable": "Romantic boutique match", "contribution": 0.25 }
      ],
      "poi_distances": { "Eiffel Tower": 3200 },
      "routes_to_pois": { "Eiffel Tower": { "walk_minutes": 38, "walk_meters": 3200 } }
    }
  ],
  "segments": [
    { "type": "text", "id": "seg-a1b2c3d4", "content": "Here's the top match for a romantic boutique Paris hotel with a rooftop bar:", "hotel_id": null },
    { "type": "hotel_ref", "id": "seg-e5f6a7b8", "content": null, "hotel_id": "a1b2c3d4-..." }
  ],
  "references": [],
  "pois": [],
  "routes": [],
  "usage": { "latency_ms": 9820, "cost_usd": 0.03 }
}

Full hotel profile - everything search results don’t include. No LLM, direct database lookup. phone_number is needed before any call_hotel request.

Response shape:

Initiate a voice call. The AI agent calls the hotel on behalf of the guest to negotiate rates, confirm bookings, or handle cancellations. Pro tier and above. The scenario parameter picks the playbook the agent runs (default hotel_negotiation). Returns a call_id immediately (202 Accepted) — poll /v1/call/{call_id}/status until completed, then fetch /v1/call/{call_id}/results for the transcript and outcome.

Initiate response (202 Accepted):

Status response (GET /v1/call/{call_id}/status):

Results response (GET /v1/call/{call_id}/results— returns 409 if the call has not yet completed):

Sixteen endpoints. One base URL.

Anything available via MCP is available via REST at https://api.vistalink.com. Same auth header, same response shapes, same rate limits. The REST API additionally exposes guest profile management for booking workflows.

Status codes, retry behavior.

All errors return a JSON body: { "error": { "code": "rate_limited", "message": "..." } }. Use the machine-readable code for retry logic; the message field is for humans. On 429, the response also carries a Retry-After header in seconds.