Subscribe
Complete Stripe checkout for Broker API from a brokerage workspace. Founding software access does not include keys.
Developer documentation
Private Charter Broker API.
A read-only professional yacht-data interface for subscribed broker websites, CRMs, client portals and internal sourcing tools.
Documentation status
Private launch · current contract
The versioned Broker API base is https://private-charter.com/api/v1. Credentials are organisation-scoped, hashed at rest, displayed once and available only after an active paid Broker API subscription.
Updated 2 October 2026
Stripe checkoutBearer credentialsCursor paginationProvenance fieldsServer-side onlyLicensed mediaStripe checkoutBearer credentialsCursor paginationProvenance fieldsServer-side onlyLicensed media
01 · Access
Start with a paid professional subscription.
The API is a controlled distribution product, not an anonymous public feed. Stripe checkout unlocks keys. That protects yacht source rights, professional contact details and the broker/private-data boundary.
Verify
Use a data-manager session with MFA when creating credentials. Distribution permissions still apply to the payload.
Activate
Issue organisation-scoped keys under Settings. The secret is shown once and hashed at rest.
API access is €250 per month on live Stripe checkout and is separate from the founding software waiver. Subscribe on the product page.
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 "https://private-charter.com/api/v1/yachts?area=West%20Mediterranean&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.
Paid API access
Subscribe, then issue your first key.
Checkout is live. Integration questions can still go to info@private-charter.com.