API Reference

The Charter Boats API is organized by who's calling:

• Discovery API (/api/ai/*) — public, no key. Conversational search for guests, AI assistants, and agents (also via MCP / Custom GPT).
• Agent API (/api/agent/*) — for approved charter agents. Reveals platform, deeplinks, and per-week activity the public search hides. Needs a logged-in agent session.
• Operator API — for owners and partners managing their own listings (boats, pricing, fees, calendar). Every call carries your key.
• Places & Data — reference data anyone with a key can read (locations, POIs, passages, sea routing, conditions).

Base URL

https://charter.boats/api

Authentication

Send your key in the X-API-Key header on every call outside the Discovery API — reads (boats, pricing, fees, locations, POIs, passages, sea routing, features, manufacturers) as well as the two writes (POST /import/boat, DELETE /boats/:id):

curl "https://charter.boats/api/boats?type=catamaran&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"
 
curl -X POST "https://charter.boats/api/import/boat" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

• No key — the request is stopped by our bot protection before it reaches the API: you get an HTML 403 page, not JSON.
• A key that isn't real — 401 {"message": "Invalid API key"}.
• The iCal feeds (/calendar/:boatId/export.ics, /calendar/company/:companyId/export.ics) are the exception: calendar apps can't send headers, so they need no key.
• The Discovery API (/api/ai/*) and the MCP server need no key — see below.

Every keyed call is recorded against your account — that is how we can see your traffic when you ask about limits, and tell it apart from an anonymous scraper's. Writes additionally check that you own the boat or company.

Call from your server: browser requests from another website are not supported (no CORS headers), with the single exception of GET /api/locations. Generate your key from Dashboard → Settings → API. See Authentication for the full rules.

Identifying yourself on open endpoints

The Discovery API (/api/ai/*) and /mcp are open: no key needed. A key is optional there, and we recommend it for any production integration. A valid API key is recorded against your account and makes the boat links in the response carry your affiliate ref (when your account has an active affiliate profile), so bookings that start from your integration are credited to you. Nothing else about the response changes, and a missing or invalid key is served exactly like an anonymous call — never a 401.

curl "https://charter.boats/api/ai/boats?l=Split" \
  -H "X-API-Key: YOUR_API_KEY"

All /api/ai/* endpoints share one rate-limit budget; past it you get 429 with a Retry-After header.

Response Format

Endpoints return data directly as JSON. Errors come back as a JSON object — read statusCode and message; statusMessage is not meaningful:

{
  "error": true,
  "url": "https://charter.boats/api/boats/no-such-boat",
  "statusCode": 404,
  "statusMessage": "Server Error",
  "message": "Boat not found"
}

A block by our bot protection (no key sent) is an HTML page with status 403, not this JSON shape.

Discovery API · guests & agents

Public, no key. Compact, fuzzy-matched results tuned for conversation. See the overview.

Agent API · approved agents

Agent-authenticated search that reveals source platform, per-yacht deeplinks, per-week availability/options, and a commission preview. Requires a logged-in agent session — see the overview.

Operator API · owners & partners

Manage your own listings. Every call carries your X-API-Key.

Boats

Pricing & Fees

Calendar

Places & Data · public reference

Read-only catalog data you can use to build on the platform. Same rule as the Operator API: send your key on every call.

Locations & POIs

Passages & Sea Routing

Conditions

Looking for booking or content endpoints?

• Booking a boat (reserve + pay) runs through the charter.boats checkout UI, not a public API -- it needs a logged-in guest session and Stripe Elements on the page.
• Articles & FAQs are searchable via the Discovery API's /ai/content.

HTTP Status Codes