Developer docs

Overview

Vulcani Aeolian Boat Rentals publishes a small public, read-only API so that AI agents and apps can answer questions about our boat tours and dinghy rentals in the Aeolian Islands (Lipari, Sicily). No authentication and no API key are needed. Bookings are not possible through the API: they happen on WhatsApp (+39 379 349 7864).

• OpenAPI 3.1 description: /openapi.json
• API catalog (RFC 9727): /.well-known/api-catalog
• MCP server (Streamable HTTP): /mcp
• llms.txt

Endpoints

• GET /api/v1/info: business name, description, phones, WhatsApp, address, coordinates, hours, languages, islands served
• GET /api/v1/experiences?lang=it|en: the six boat experiences we offer
• GET /api/v1/faq?lang=it|en: frequently asked questions and answers

curl -s https://vulcaniboatrentals.com/api/v1/info
curl -s 'https://vulcaniboatrentals.com/api/v1/experiences?lang=en'
curl -s 'https://vulcaniboatrentals.com/api/v1/faq?lang=it'

MCP server

The same data is available as read-only MCP tools (get_business_info, list_experiences, list_faq) and resources over Streamable HTTP at https://vulcaniboatrentals.com/mcp (JSON-RPC 2.0, POST only, no auth).

curl -s https://vulcaniboatrentals.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_experiences","arguments":{"lang":"en"}}}'

Markdown

Every public page (/, /en/, /about/, /contact/, /privacy/, /docs/) is also available as Markdown: send the header Accept: text/markdown.

curl -s https://vulcaniboatrentals.com/en/ -H 'Accept: text/markdown'

Rate limits

The API and the MCP server allow 60 requests per minute per IP address. Every response carries the IETF headers RateLimit-Policy and RateLimit (remaining requests and seconds until the window resets; the remaining count is tracked per edge location, so treat it as approximate). Over the limit you get HTTP 429 with a Retry-After header.

Errors

Errors under /api/ use application/problem+json (RFC 9457) with the fields type, title, status, detail, code and resolution. Examples: 400 invalid_parameter, 404 not_found, 405 method_not_allowed, 429 rate_limited.

{
  "type": "https://vulcaniboatrentals.com/docs/#errors",
  "title": "Not Found",
  "status": 404,
  "detail": "No API endpoint at /api/v1/boats.",
  "code": "not_found",
  "resolution": "See https://vulcaniboatrentals.com/openapi.json for the list of endpoints."
}

Versioning

The API is versioned in the path (/api/v1/). Changes inside v1 only add fields; a breaking change would ship as /api/v2/ with v1 kept online.