Aruba Sightseeing Tours · by Aruba Your Way

Private van-tour assistant API

Read the tour facts, explore all 25 stops, calculate a group price, and open the secure booking form with a plan already filled in.

Version 1.2.0. No API key needed. Planning endpoints do not create a reservation, save a card, send an email or charge money. The separate question endpoint sends an email only with customer permission. The guest reviews and completes booking on our website.

1. Check the tour fits

GET service for policies and GET stops for exact IDs and separate admission rules. Answers and qualifications are in the public facts page and complete FAQ.

2. Request a quote or a booking link

curl https://arubasightseeingtours.com/van-tour/api/v1/handoff.php \
  -H 'Content-Type: application/json' \
  --data '{
  "adults": 7,
  "children": 0,
  "duration_hours": 4,
  "stop_ids": [
    "california-lighthouse",
    "tres-trapi",
    "bushiribana",
    "casibari"
  ]
}'

Use quote.php if you need only the price. The three counts are required JSON integers. Adults are ages 13+; children are ages 0–12 and ride free but count toward capacity. Minimum 1 adult; maximum 10 guests per van, up to four vans with explicit passenger allocations. The tenth seat is compact, perfect for a child or small person.

Choose 4–8 whole hours. stop_ids is optional; an empty list means decide with the guide. The 25 IDs come from the catalog. Stops are a wish list, not a validated driving route.

Optionally supply both tour_date (YYYY-MM-DD) and pickup_time (such as 13:00). Use America/Aruba, UTC−04:00 all year, in 15-minute steps. Online booking needs at least 24 hours’ notice. Dates must be in the future; example dates should never be copied as fixed availability.

3. Read the result

The example returns this price object. Amounts are whole USD, never cents. The total is for the entire group, not per person.

{
  "base": 399,
  "extra_adults": 400,
  "subtotal": 799,
  "tax_and_card_fee": 71,
  "total": 870,
  "amount_due_today": 0,
  "money_unit": "whole_USD",
  "attraction_admission_included": false
}

schedule_validated only checks date/time syntax and advance notice. inventory_checked, route_feasibility_checked and booking_created are false. admission_total is null because attraction age bands and optional activities differ from the tour fare categories. Read selected_attraction_fees and warnings.

One Arikok admission covers both caves. Do not charge it twice. Do not turn the free lighthouse setting into a mandatory tower-climb fee. For detailed age bands, use the catalog, not the tour’s free-child age band.

4. Hand off to secure booking

Open handoff.url exactly as returned, including its fragment. The website imports the plan and removes it from the address bar. The link is an editable suggestion, not a reservation or signed price. The guest reviews the current quote, provides contact details, accepts the terms and saves a card directly in Stripe’s fields.

Only successful booking completion produces a confirmed reference. A saved card, quoted total, itinerary or handoff response alone is not confirmation. No charge today. Our team charges your card 24 hours before your tour. Cancel or change your details free before then. Cancellations within 24 hours and no-shows are charged the full tour price. Your card is saved for this booking only. The statement descriptor is BRUMMELL AND FOGG LLC.

Never send names, contact details, pickup addresses, card numbers, security codes, consent flags or a price override to the planning API. Unknown fields are rejected. Do not call protected booking endpoints directly or bypass guest consent. An uncertain submission should be recovered in its existing session; do not start another booking to get around it.

Booking states and changes

The full-screen dialog exposes data-flow (builder or booking), data-checkout-step (1–3), and data-booking-state. Builder stages are length, cards and summary. These are observable UI states, not credentials or authorization to submit.

Booking completion requires the protected browser session, explicit consent and Stripe. There is no charge or direct public amendment/cancellation endpoint. Existing-reservation lookup requires verified guest delegation, described below. Do not claim an amendment or cancellation succeeded from merely sending a question.

Guest-approved drafts and reservations

assess_van_tour_request accepts a Plan plus explicit requirements. It returns an exact quote, evidence links, unmet requirements and qualifications. It cannot verify live inventory, exact drive times, opening hours or sea conditions.

Use create_van_booking_draft with permission to store an encrypted draft and optional contact/pickup details. Generate a private random 32-byte hex request_key; preserve it and identical input for retries. The draft expires in 24 hours. It is not an inventory hold or booking. Send customer_approval_url to the guest without changing its fragment. The website removes the fragment before analytics and lets the guest edit every field, consent to sharing the result, accept the terms, and save a card directly with Stripe.

Keep the separate operation_id and operation_token private. Call get_van_booking_outcome at most once every 15 seconds. A verified receipt yields confirmed, reference and final total; processing or action_required do not. After submission the outcome credential lasts seven days. This is the original creation outcome, not current amendment status. Do not create duplicate drafts/bookings after an uncertain response.

For an existing reservation, call request_van_reservation_access with its reference and a fresh private request_key. This sends no email or reservation details. Give the returned approval link to the guest. On the website, they enter the booking email, receive a six-digit code, enter it there and explicitly grant one hour of access. Never ask the guest to tell an assistant the code. The guest can revoke access from the same link.

After authorization, get_van_reservation returns only this reservation’s tour details and request statuses, not contact/card/internal data. preview_van_reservation_request prepares a pickup change, date/time change, or cancellation. Show the guest the proposed action, deadline and potential charge, then ask permission. Send the signed 15-minute proposal to submit_van_reservation_request with that approval. Preserve its random UUID v4 request_id and exact proposal on retries.

A received request remains pending. Only Thalia can approve or decline it in the booking system. Read the reservation again for completed or rejected and the team’s response. A changed reservation or newly crossed cutoff requires a fresh preview and renewed guest approval. The deadline is measured when the request is received, not when the team opens it. No tool charges, refunds or automatically waives a fee. For urgent pickup/deadline issues, call the team.

Private credentials are bearer capabilities: anyone holding one has its narrowly limited access until expiry/revocation. Do not log, publish or put them in query parameters. Approval links, proposal tokens and personal data must not enter analytics. These operations are served through the same MCP and WebMCP tools, or POST operation.php with the OpenAPI-documented action wrapper. Browser origins are restricted; remote clients omit Origin. This is separate from the anonymous, stateless planning API.

Agent tool adapters

The public MCP endpoint is https://arubasightseeingtours.com/van-tour/api/v1/mcp.php. Use Streamable HTTP POST with Accept: application/json, text/event-stream and JSON content. No API key, cookies or OAuth are needed for planning or authorized inquiries. Inquiry submission is a write operation with shared abuse controls.

Five planning tools, including assess_van_tour_request: get_van_tour, list_van_stops, quote_van_tour, prepare_van_booking_link. The last two take the same Plan input as the REST API. Tool schemas are generated from OpenAPI. Tool errors have isError: true; no error is a reservation.

Protocol 2026-07-28 uses per-request metadata: params._meta must contain io.modelcontextprotocol/protocolVersion and object io.modelcontextprotocol/clientCapabilities. Include matching MCP-Protocol-Version, Mcp-Method, and, for tools/call, Mcp-Name headers. Start with server/discover or tools/list. Legacy 2025-11-25 and 2025-06-18 clients use initialize, then the protocol-version header. The MCP transport has no sessions or SSE subscriptions. Private operations have separate durable expiring state and capabilities. GET/DELETE return 405. Unknown browser origins are rejected; remote clients normally omit Origin.

On browsers with document.modelContext.registerTool, the homepage also exposes the same twelve tools, including protected guest-approved operations. Unsupported browsers simply use the normal interface. The planning handoff returns a link; it never opens checkout, submits booking consent or makes a reservation automatically. The question tool requires customer permission and shares their reply email with the team. WebMCP remains experimental and client support varies.

llms.txt is an optional directory to the same public facts and tools. It is not a ranking signal guarantee or a substitute for the visible tour and FAQ.

Ask the team, with customer permission

Use send_tour_question over MCP or POST /van-tour/api/v1/question.php. This is a consequential email action, not a read-only lookup. Ask the customer before sending or sharing their email. The server cannot verify a caller’s claimed permission and does not trust a bot name, user-agent header or “I’m an AI” claim.

Supply a fresh random UUID v4 request_id, reply_email, a plain-text question (5–3,000 characters), optional name, and customer_authorized: true. Never send card/account numbers, secrets or attachments. The fixed recipient is configured privately on the server; callers cannot choose it. The team replies to the supplied email through its normal support workflow.

status: received and a reference such as AYW-Q-… mean the mail transport accepted the inquiry, not that someone has read it or that inbox delivery is guaranteed. No booking, amendment or cancellation has been made. Preserve the reference for follow-up.

Retry with the same UUID and identical content for up to seven days. A lost response, timeout or delivery_uncertain must not trigger a new UUID or another email. A changed payload with the same UUID returns 409. Identical content is also deduplicated across browser sessions and channels for seven days. After that, ask the team rather than replaying an old uncertain request.

Shared limits apply by network address, hashed reply email, hour and day. Honor 429 and retry_after_seconds. Messages flagged for suspicious content return verification_required without sending; a person can verify the inquiry by phone. These checks reduce spam, not guarantee its elimination. A customer may instead use the question form.

Call (305) 424-8326, 8am–4pm daily, Aruba time. The public recipient email is deliberately not exposed. Message contents and reply email go only into the private email workflow, not into URLs, analytics or tool responses. The server stores only HMAC fingerprints, counters, receipt states and references for duplicate/rate control; expired entries are pruned on subsequent requests.

Endpoints

Errors and retries

{"error":{"code":"invalid_plan","message":"Unknown stop ID. Read the stops catalog."}}

Public planning requests are stateless, accept no credentials, and create no server-side planning records. CORS is allowed without cookies. Quote/handoff requests can safely be retried; this does not apply to submitting a real booking. Do not infer a free price or confirmation from an error.

Facts updated 2026-10-14; pricing version van-2026-10-13. Generated from the same approved public contract as the website. Callers should tolerate additional response fields; breaking changes require a new API version.