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, booked rate, and a commission preview.
The same data is exposed over HTTP at /api/agent/boats.
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 a cb_live_ 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 |
|---|---|
| Admin mints an invite | POST /api/admin/agents/invite → { token, url } |
| Agent opens the invite | GET /pro-gated landing at /agent/join/{token} |
| Redeem (single-use) | POST /api/agent/claim/{token} — signs in, then activates the agent profile |
Once active, the Pro search mode appears on the homepage and /pro is reachable.
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 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; 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).
- Reserve via us — the standard charter.boats booking flow.
The response platform field marks which of these is the price-of-record for the boat.
Commission figures are a pre-booking estimate and are gated to 0 until the agent has completed at least one booking. The exact figure is only known at booking time from the platform's payout data.