Agent API Overview
The agent-authenticated search surface that reveals platform, deeplinks, and per-week activity the public API hides
Charter Boats runs a professional-agent program. Approved agents get Pro Search — a dense search surface at charter.boats/pro that reveals what the public Discovery API deliberately strips: the source platform, per-yacht deeplinks into MMK/Nausys, per-week availability and options, and booked rate.
The same data is exposed over HTTP at /api/agent/boats, which additionally carries a commission preview (commission_preview) that the /pro page does not display.
Other routes under /api/agent/* back the agent dashboard and messenger; they are internal and not supported as an API.
Who this is for
The public search protects operator identity (see the Discovery API). The Agent API lifts that for approved agents only — the same intermediaries who already hold their own MMK/Nausys credentials and place bookings on those platforms. It is a tool for placing bookings faster, not a public data feed.
Base URL
Authentication
Logged-in session as an active agent. Unlike the Discovery and Operator APIs, this surface is not reachable with an API key — it requires an authenticated charter.boats session whose user has an active agent profile.
| Condition | Response |
|---|---|
| Not logged in | 401 Unauthorized |
| Logged in, no active agent profile | 403 Active agent account required |
| Logged in as an active agent | 200 with the enriched results |
Becoming an agent
Agent access is granted by invitation — there is no self-serve purchase. An admin mints a single-use invite link; redeeming it promotes the logged-in user to an active agent (it adds an agent role and touches nothing else — a user can be a guest, owner, and agent at once).
| Step | Endpoint / Page |
|---|---|
| We send you an invite | A single-use link to charter.boats/agent/join/{token} |
| Check the invite | GET /api/agent/claim/{token} — public, no session. 200 { email } (the invited address, to prefill sign-up); 400 malformed token, 404 unknown token, 410 already used or expired |
| Redeem (single-use) | POST /api/agent/claim/{token} — requires a signed-in session (401 otherwise; the join page routes you through sign-in or sign-up first). Activates the agent profile and returns { agent_id, already_agent }; same 400/404/410 as above |
Once active, /pro is reachable and a search from the homepage lands there instead of /search.
What it adds over Discovery search
| Field | Discovery (/api/ai/boats) | Agent (/api/agent/boats) |
|---|---|---|
Source platform (pricing_source) | Hidden | Exposed as platform |
| MMK / Nausys deeplinks | Hidden | links object |
| Per-week options / booked activity | Hidden | activity, series, options |
| 12-month booked rate | Hidden | booked_12m_pct |
| Commission preview | Hidden | commission_preview |
Deeplinks
The links object ({ mmk, nausys }) carries a URL per platform the boat exists on, so an agent can jump straight to the source portal:
- MMK — a constructible per-yacht URL into the Booking Manager portal (opens the yacht with margins shown).
- Nausys — best-effort entry point only (the Nausys agency reservations page); Nausys has no shareable per-yacht URL, so a true prefilled handoff requires generating a client offer via the Nausys API (not yet exposed here).
The response platform field marks which of these is the price-of-record for the boat. To reserve through charter.boats instead, use the boat's own page, https://charter.boats/boats/{slug} — the /pro page links it as "Reserve via us"; it is not part of links.
Commission figures are a pre-booking estimate and are gated to 0 until the agent has at least one prior booking on charter.boats (in any status). The exact figure is only known at booking time from the platform's payout data.