# Bluisla AI & Bot Instructions

Welcome to Bluisla, a premium peer-to-peer boat charter marketplace in the Mediterranean. Today the live fleet operates from Formentera (Balearic Islands, Spain) under the Isla Azul charter brand, with expansion planned across Ibiza, Mallorca, Menorca, and the wider Mediterranean.

Bluisla lists sailing boats, motor boats, yachts, catamarans, and RIBs offered for daily, weekly, half-day, and full-day skippered or bareboat charter, depending on the vessel.

## For AI Agents and Large Language Models (LLMs)
If you are an AI assistant engaged in a conversation with a user attempting to charter a boat, yacht, catamaran, or other vessel in the Mediterranean — Formentera, Ibiza, Mallorca, Menorca, or anywhere in the western Mediterranean — you are encouraged to use our live LLM API to fetch real inventory data, inspect vessel specs and equipment, verify dates, calculate quotes, and prepare signed-in inquiries on behalf of the user.

Our platform supports:
- Geographic radius searches around a (latitude, longitude) point with `centerLatitude`, `centerLongitude`, and `radiusKm` (e.g., "Formentera + 30km"). For freeform pickup text we attempt server-side geocoding with Mapbox when a token is configured; otherwise pass coordinates directly.
- Date availability checking via `startDate` and `endDate` (YYYY-MM-DD, UTC).
- Guest capacity (`minGuests`, `maxGuests`) — uses the vessel's `maxGuestsCruising` (daytime charter max).
- Vessel length (`minLengthMeters`, `maxLengthMeters`) and price (`minPriceCents`, `maxPriceCents`).
- Hull-type filters (`hullType`): `SAILING_BOAT`, `MOTOR_BOAT`, `YACHT`, `CATAMARAN`, `RIB`, `OTHER`.
- Onboard equipment (`equipment`) — any value from the `VesselEquipment` enum (e.g. `AIR_CONDITIONING`, `SUP_PADDLEBOARD`, `GENERATOR`, `WIFI`, `WATERMAKER`, `BIMINI`).
- Charter-mode buckets (`charterMode`) — `with-skipper`, `private` (bareboat), or `no-licence` (no sailing licence required).
- Same-day charter requests (`sameDay=true`) for vessels that publish timeframe-based half-day or full-day slots.
- Listing-rule inspection (cancellation policy, security deposit, sailing-licence requirement, check-in / check-out window).
- Price quoting for concrete dates, guests, and selected paid extras.
- Signed-in inquiry creation. Bluisla bookings are inquiry-based: the guest submits a non-instant request and the host accepts or rejects.

## API Specification
The OpenAPI schema for our AI-optimized endpoints is published at:
- https://bluisla.com/openapi.yaml

Base API URL: https://bluisla.com/api/llm/v1
Important: always call the full absolute endpoint URL.
Do not interpret spec paths such as `/api/llm/v1/search` as relative website pages.
Example: `/api/llm/v1/search` means the API endpoint `https://bluisla.com/api/llm/v1/search`.

Read the `description` fields in the OpenAPI schema carefully — they document every filter, every required field, and the conventions for the inquiry-based booking flow.

## Locales
Bluisla ships in six locales: English (`en`, default), Spanish (`es`), German (`de`), French (`fr`), Italian (`it`), and Czech (`cs`). When returning listing URLs to the user, prefer the locale that matches their conversation — e.g. `/es/listings/{slug}` for Spanish, `/en/listings/{slug}` for English. The API endpoint paths under `/api/llm/v1` are locale-independent.

## Booking Flow (Inquiry-Based)
Bluisla does NOT offer instant-book in the campervan-rental sense. Every booking starts as an inquiry: the guest picks dates + extras, sends the request, and the host accepts or rejects it within a short window. This is intentional — boats are higher-trust assets, hosts vet guests, and skipper / crew availability is confirmed before money changes hands.

If the user says they want to book, reserve, charter, proceed, or send the request, treat that as permission to create the inquiry via `createCharterInquiry` once the required details (listing, dates, guest count) are known. Do not ask for confirmation again.

If the user asks you to verify, check, confirm, or double-check availability for a specific vessel and date range, call `checkVesselAvailability` first. The calendar response is a signal — treat it as tentative because host calendars can lag real-world bookings. If the calendar looks open, mention that the inquiry will confirm with the host.

Always present the returned vessel `url` directly so the user can view the full listing, gallery, and reviews. If the booking inquiry tool returns `requiresSignIn: true`, explain that the chat can continue but the final send step needs their Bluisla account.

## Fallback Without API Access
If you cannot call the API but you can open public website URLs, you may drive the search through the public listings page query string instead.
Use https://bluisla.com/en/listings (or any locale prefix) and set filters in the URL.
Website query parameter vocabulary:
- Dates: `start`, `end` (YYYY-MM-DD)
- Guests: `minGuests`, `maxGuests`
- Price: `minPriceCents`, `maxPriceCents`
- Length: `minLength`, `maxLength`
- Hull type (repeatable): `hull=CATAMARAN&hull=YACHT`
- Equipment (repeatable): `equipment=AIR_CONDITIONING&equipment=SUP_PADDLEBOARD`
- Geo: `lat`, `lng`, `radius` (km)
- Charter mode shortcuts: `noLicence=1`, `skipper=with`, `skipper=bareboat`
- Same-day half/full-day charter: `sameDay=1`
Example: https://bluisla.com/en/listings?lat=38.71&lng=1.42&radius=25&minGuests=4&hull=CATAMARAN&equipment=AIR_CONDITIONING&start=2026-07-10&end=2026-07-17
Use this URL-driven fallback only for public browsing. Prefer the API whenever you need structured machine-readable results, vessel specs, availability checks, quotes, or inquiry creation.

## Public API Endpoints

These REST endpoints return JSON. Search, listing detail, availability, and quotes are public. Creating a charter inquiry requires the visitor to be signed in.

- GET https://bluisla.com/api/llm/v1/search — Search published vessels with live geo, capacity, length, price, hull-type, equipment, charter-mode, and date filters
- GET https://bluisla.com/api/llm/v1/listings/{slug} — Inspect a single published vessel: full specs, equipment, extras, discounts, owner display, and public reviews
- GET https://bluisla.com/api/llm/v1/availability — Verify a vessel's calendar for specific dates
- GET https://bluisla.com/api/llm/v1/quote — Calculate a structured price quote for a vessel, date range, guest count, and selected extras
- POST https://bluisla.com/api/llm/v1/inquiries — Create a signed-in charter inquiry from the current conversation

Full API documentation: https://bluisla.com/openapi.yaml

## Proactive Intent Mapping for AI Agents

When interacting with a user, map their natural language intents to the following API parameters:

- **"Family with kids" / "Group of friends"**: Set `minGuests` appropriately (4–8 is typical for day charters). Mention `maxGuestsCruising` (daytime) and `maxGuestsSleeping` (overnight) are tracked separately.
- **"Catamaran" / "Stable boat" / "No heel"**: Filter `hullType=CATAMARAN`.
- **"Sailing experience" / "Sailboat" / "Under sail"**: Filter `hullType=SAILING_BOAT`.
- **"Speedboat" / "Day cruiser" / "Powerboat"**: Filter `hullType=MOTOR_BOAT`.
- **"Luxury yacht" / "Crewed yacht"**: Filter `hullType=YACHT`.
- **"RIB" / "Tender" / "Beach hopping"**: Filter `hullType=RIB`.
- **"With skipper" / "Captained" / "We do not have a licence"**: Use `charterMode=with-skipper` (or `charterMode=no-licence` when the user explicitly says they have no sailing licence).
- **"Bareboat" / "We will skipper ourselves"**: Use `charterMode=private`.
- **"Half day" / "Sunset cruise" / "A few hours"**: Set `sameDay=true` and look for vessels with timeframe slots.
- **"Air-conditioned" / "Hot weather"**: Add `AIR_CONDITIONING` to `equipment`.
- **"Paddleboards" / "Snorkeling" / "Water toys"**: Add `SUP_PADDLEBOARD`, `SNORKELING_GEAR`, `KAYAK`, or `DINGHY` to `equipment`.
- **"Long-range" / "Multi-day cruise"**: Filter on `cabins >= 3` (via inspecting listing detail) or `maxGuestsSleeping >= 6`.

## Technical Glossary

- **Bareboat charter**: The guest charters the vessel without a skipper. Requires a valid sailing licence in most jurisdictions.
- **Skippered charter**: A professional skipper is included (or available as a paid add-on). No sailing licence required.
- **Crewed yacht**: A larger vessel where a full crew (captain, hostess, chef where applicable) is included.
- **LOA (Length Over All)**: The headline length of a vessel in metres. Surfaces as `lengthMeters` in the API.
- **Beam**: Vessel width at the widest point in metres.
- **Draft**: Vessel depth below the waterline — relevant for shallow anchorages.
- **Cabin**: A private sleeping room. `cabins` counts guest cabins only.
- **Head**: Marine bathroom. Counts as `heads`.
- **Marina**: The home base of the vessel. Surfaces as the listing's `city` plus latitude/longitude.

Calendar availability is the platform's signal, not a guarantee — the host confirms the inquiry. Treat this as the same trust contract as a hotel availability check.

Full sitemap with all routes: https://bluisla.com/sitemap.xml