Authentication

Authentication depends on which surface you're calling:

The Discovery API, the MCP server and the iCal feeds need no credentials. Everything else under /api/* — boats, pricing, fees, locations, POIs, passages, sea routing, features, manufacturers — expects your key in the X-API-Key header on every request, reads included.

Which surface is built for you?

A keyless surface is not "the free tier" and a key is not "the partner tier". The split is whether your caller can hold a secret at all, and whether you are answering one question or pulling data in bulk.

Two things follow, and they are what people get wrong in both directions:

Don't reach for a key you don't need. If you are an AI agent, a Custom GPT or an MCP host answering one traveller at a time, the Discovery API is built for exactly that and needs no credential — many such callers cannot safely hold one. Sending a key is still worth it, because it credits bookings from your integration to your affiliate profile, but it is never required and an invalid one is ignored rather than refused.

Selling boats you don't operate goes through the Discovery API. The Operator API reads only the boats of companies you are a member of — what you entered, so you can check it. Another operator's boat answers 403 there. The Discovery API gives you every boat with the price the guest pays on charter.boats, and its links send the buyer to us with your affiliate ref. Send your key with it: without one the budget is shared per IP (or per Custom GPT end user); with one it is your own.

When do you actually need the key?

# Reads carry the key
curl "https://charter.boats/api/boats?company_slug=your-company&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"
 
# So do writes — with a JSON body, send the Content-Type too
curl -X POST https://charter.boats/api/import/boat \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

What happens without a valid key:

• No key — our bot protection stops the request before it reaches the API and answers with an HTML 403 page, not JSON. If you see HTML where you expected JSON, check the header is being sent.
• A key that isn't real — 401 Invalid API key. Keys are checked on every call, not just on writes.
• A malformed key — treated like no key: bot protection answers the HTML 403.
• A boat your company does not operate — 403 JSON naming the Discovery API. So is GET /boats without company_slug set to your own company.

Every keyed call is recorded against your account, so we can see your usage when you ask about it.

Browsers on other websites

Call the API from your server. Browser requests from another website are not supported: responses carry no CORS headers, so the browser refuses to hand them to your page — and a key in client-side code is a leaked key anyway. The single exception is GET /api/locations (the exact path — the location autocomplete index), which answers cross-origin so the embeddable search widget's location box works. Anything else: proxy it through your own backend.

The Discovery API

/api/ai/* and /mcp never refuse a caller over its key. Sending one is still worthwhile: a valid API key records the call against your account, 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 — and it raises your rate limit substantially (see below). An invalid key is ignored — never a 401.

Rate limits

Your key buys one budget, spent across both keyed surfaces — the Discovery API and the keyed read API. Use it wherever you like.

The daily budgets reset at 00:00 UTC. Every 429 names the limit it hit and links to the same search on charter.boats, so an assistant can send its user to the site.

Every keyed response carries its daily budget in the headers:

Past any limit you get 429 with a Retry-After header — seconds for the per-minute brake, seconds until midnight UTC for the daily ones. The detail limit refuses only detail calls: search keeps answering. Read X-RateLimit-Remaining and pace yourself rather than retrying into the wall.

What you can't do with a key

The key gives you your own fleet: read it — unpublished boats included, through List Your Fleet — import, update and delete boats, and set their prices, fees, photos and videos, calendar and your company's discounts. Transactional actions — booking, paying, answering a booking request — are tied to a logged-in session on charter.boats and are not exposed as keyed endpoints.

Which companies a key covers

A key belongs to your user account, not to one company. It works for every company your account is a member of: each call checks that you are a member of the boat's company, and deleting a boat needs an owner or admin role there. List Your Fleet without company_id returns the boats of all of them, each row with its company_id; pass company_id to read one. To connect several independent owners, each owner uses their own account and key.

Getting an API Key

Any registered user can generate an API key from the dashboard:

1. Log in to charter.boats
2. Go to Dashboard → Settings → API
3. Read and accept the API usage terms
4. Click Generate API Key
5. Copy and save your key (it is only shown once)

Regenerating Your Key

If your key is compromised, you can regenerate it from the same settings page. This will immediately invalidate your old key. If the API terms have changed since you accepted them, the page asks you to accept them again before issuing a new key.

Security Best Practices

Recommendations

Error Responses

Errors are JSON with the status in statusCode and the reason in message (see Response Format). The one exception is a request with no key at all: that is stopped by bot protection and comes back as an HTML 403 page.

401 Unauthorized

{
  "error": true,
  "url": "https://charter.boats/api/boats?limit=1",
  "statusCode": 401,
  "statusMessage": "Server Error",
  "message": "Invalid API key"
}

403 Forbidden