Apply
Describe the brokerage, systems, markets and intended public or internal use.
Developer documentation
Private Charter Broker API.
A read-only professional yacht-data interface for approved broker websites, CRMs, client portals and internal sourcing tools.
Documentation status
Private launch · current contract
Production credentials and the active base URL are issued after organisation and data-rights review. The website's internal /api/* routes are not the Broker API and must not be integrated against.
Published and reviewed 31 August 2026
01 · Access
Start with an approved professional use case.
The API is a controlled distribution product, not an anonymous public feed. Approval protects yacht source rights, professional contact details and the broker/private-data boundary.
Review
Private Charter confirms the organisation, data scope and relevant distribution permissions.
Activate
The approved technical contact receives the base URL, credentials, limits and onboarding record.
API access is €250 per month and is separate from the founding software waiver. Review the product and pricing.
02 · Authentication
Keep credentials on the server.
Every production request uses an organisation-scoped bearer credential. Never expose it in browser JavaScript, a public repository, a mobile bundle or an analytics event.
Server-side request
curl --request GET \
--url "$PRIVATE_CHARTER_API_BASE/yachts?area=west-mediterranean&limit=50" \
--header "Authorization: Bearer $PRIVATE_CHARTER_API_KEY" \
--header "Accept: application/json"Credential handling
Store the key in a managed server secret, restrict access to the integration service and rotate it immediately after suspected disclosure.
Rotation
A replacement key can overlap briefly during a planned rotation. Retire the old key as soon as the new one is confirmed in production.
03 · Resources
A stable yacht identity with time-stamped professional claims.
The feed separates the canonical yacht from changeable charter facts. Collection responses are cursor-paginated; the activation record states the available resources and account limit.
Identity
Stable yacht ID, display name, yacht type and canonical record state.
Dimensions & capacity
Length, guest capacity, cabin count and other supplied specifications. Missing values remain null or absent.
Charter terms
Published rate range, currency, season or area context and the timestamp of the source record.
Availability state
Operational status such as confirmation_required, requested, held, confirmed, declined or expired—not a fabricated Boolean.
Media
Authorised image and brochure references only where the source permits API distribution.
Representation
Professional representative details only where the listing owner permits distribution to the approved brokerage.
Representative yacht response
{
"id": "yacht_01J...",
"name": "Example Yacht",
"type": "motor_yacht",
"length": { "metres": 42.0, "feet": 137.8 },
"guests": { "cruising": 12, "sleeping": 10 },
"cabins": 5,
"build": { "year": 2021, "refit_year": null },
"charter": {
"currency": "EUR",
"weekly_rate_from": 145000,
"weekly_rate_to": 165000,
"areas": ["West Mediterranean"],
"availability_status": "confirmation_required"
},
"provenance": {
"source_type": "central_agent",
"verified_at": "2026-08-28T14:20:00Z"
},
"updated_at": "2026-08-28T14:20:00Z"
}04 · Data semantics
Unknown is not false. Open is not confirmed.
Null and absent fields
A null or absent field means the current authorised source did not provide a reliable value. Do not render zero, no or unavailable unless the response explicitly says so.
Availability
confirmation_required means no deal-specific confirmation exists. requested, held, confirmed, declined and expired are distinct time-bound states.
Rates
A published weekly rate is not an all-in quote. Currency, season, APA, tax, delivery and source time must remain visible in the consuming product.
Freshness
Use updated_at and provenance. A cached record may remain useful for discovery while still requiring current professional verification before a proposal.
05 · Pagination, limits & errors
Design for bounded, observable requests.
Use the returned cursor rather than calculating pages. Respect the account-specific limit headers and back off after a rate response. Include request_id when contacting support.
| Status | Meaning | Integration action |
|---|---|---|
| 400 | Invalid request or filter | Correct the request; do not retry unchanged. |
| 401 | Missing, invalid or retired key | Stop and verify the server-side credential. |
| 403 | Resource or use is outside the approved scope | Do not bypass; contact the account owner. |
| 404 | Resource not visible or no longer published | Remove or mark the cached record unavailable. |
| 429 | Account limit reached | Use Retry-After and exponential backoff. |
| 5xx | Temporary service failure | Retry safely with backoff and a bounded attempt count. |
Error envelope
{
"error": {
"code": "invalid_request",
"message": "The supplied area filter is not recognised.",
"request_id": "req_01J..."
}
}06 · Rights, caching & security
The payload does not erase the source licence.
API access grants an approved use of distributed fields; it does not transfer ownership of yacht imagery, brochures, private contact details or the underlying database.
Cache deliberately
Use the cache period and deletion rules in the activation record. Revalidate records that affect a live client decision.
Minimise display
Publish only the fields and media permitted for the approved channel. Keep professional-only contacts behind professional access.
No data laundering
Do not strip attribution, bypass visibility rules, resell the feed or use it to reconstruct private brokerage information.
Integration support
Plan the first API connection with us.
Send the intended system, markets, audience and technical contact to info@private-charter.com.