Book Now
Book Now

All'ombra del Vesuvio Rooms API and MCP server

A public, read-only API with the same data you see on this website: apartments in Naples and Sorrento, travel guides and local experiences. Use it from scripts, apps or AI agents. The API cannot create bookings: to book, open the apartment page and send the booking request form.

Base URL and authentication

Base URL: https://allombradelvesuviorooms.com. No authentication and no API key. CORS is open. Machine-readable spec: /openapi.json (OpenAPI 3.1), catalog: /.well-known/api-catalog.

Endpoints

  • GET /api/v1/info — Business name, address, email, phone, check-in times, price range.
  • GET /api/v1/apartments?lang=en|it — All apartments with capacity, rating and starting price per night (EUR).
  • GET /api/v1/apartments/{id}?lang=en|it — One apartment: description, amenities, nearby places, transport.
  • GET /api/v1/apartments/{id}/availability?checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD — Live availability, minimum stay and alternative dates.
  • GET /api/v1/apartments/{id}/quote?checkIn=...&checkOut=...&adults=2&children=0 — Exact price in EUR for a direct booking, with availability.
  • POST /api/v1/booking-requests — Booking request for free dates (JSON body). The host replies to the guest by email within about 24 hours.
  • GET /api/v1/guides?lang=en|it&category=History — Travel guides for Naples and Campania.
  • GET /api/v1/experiences?lang=en|it — Tours and experiences recommended to guests.
  • GET /api/v1/discounts?lang=en|it — Partner discount codes for boat tours: code, % off, partner, booking link.

Examples

curl https://allombradelvesuviorooms.com/api/v1/apartments
curl "https://allombradelvesuviorooms.com/api/v1/apartments/vomero?lang=it"
curl "https://allombradelvesuviorooms.com/api/v1/guides?category=History"
curl https://allombradelvesuviorooms.com/guides/pompeii.md

Rate limits

60 requests per 60 seconds per client IP, counted per edge instance. Every response carries the IETF headers RateLimit-Policy (for example "default";q=60;w=60) and RateLimit (r = remaining, t = seconds to reset). Over the limit you get HTTP 429 with Retry-After.

Errors

Errors use application/problem+json (RFC 9457) with the fields type, title, status, detail, code and resolution. Codes: not_found, apartment_not_found, invalid_lang, rate_limited, invalid_dates, stay_too_long, too_many_guests, invalid_contact, invalid_body, minimum_stay, dates_unavailable, request_limit, email_unavailable.

{
  "type": "https://allombradelvesuviorooms.com/docs#errors",
  "title": "Apartment not found",
  "status": 404,
  "detail": "No active apartment with id 'xyz'.",
  "code": "apartment_not_found",
  "resolution": "List the valid ids with GET /api/v1/apartments."
}

MCP server

Streamable HTTP endpoint: https://allombradelvesuviorooms.com/mcp (JSON-RPC 2.0 over POST, no auth). Server card: /.well-known/mcp/server-card.json. Read-only tools:

  • check_availability — Whether an apartment is free for the given dates (live from the host calendar, refreshed every 15 minutes), the minimum stay for that check-in day, and up to 3 alternative dates of the same length if not.
  • get_quote — Exact price for a stay booked directly with us: nights, extra-guest supplement, long-stay discount, total in EUR (no guest service fee, lower than on Airbnb), plus the Naples city tax paid on site. Includes availability.
  • request_booking — Books free dates with the guest's name and email (ask the user before calling). When online payment is active it returns paymentUrl: give it to the user, who pays the deposit (30%, or the whole stay if arrival is within 14 days) on Stripe within 30 minutes; the booking is confirmed when paid. Otherwise it is a request and the host replies by email within about 24 hours. The agent never handles card data.
  • get_business_info — Name, address, email, phone, check-in/check-out times and price range of All'ombra del Vesuvio Rooms.
  • list_apartments — Apartments offered in Naples and Sorrento with capacity, starting price per night (EUR) and booking link.
  • get_apartment — Full detail of one apartment: description, amenities, nearby places, transport. Use an id from list_apartments.
  • list_guides — Travel guides for Naples and Campania (sights, food, transport, day trips). Optional category filter.
  • list_experiences — Tours and local experiences recommended to guests.
  • list_discount_codes — Discount codes for boat tours in Naples, Capri, Ischia, Procida and the Amalfi Coast (code, % off, partner, booking link). Use when a user looks for a discount or promo code for these tours.

Resources: vesuvio://business, vesuvio://apartments, vesuvio://experiences, vesuvio://discounts (application/json).

curl -X POST https://allombradelvesuviorooms.com/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_apartments","arguments":{}}}'

Claude Code: claude mcp add --transport http vesuvio-rooms https://allombradelvesuviorooms.com/mcp

Markdown and llms.txt

Every page has a markdown version: add .md to its URL (/guides/pompeii.md, /index.md for the home page). A summary for language models is at /llms.txt.