Live API · v1 · 99.99% SLA
YH Charter API Documentation A RESTful API for yacht discovery, availability, quoting, and booking. JSON bodies over HTTPS, predictable resource URLs, Bearer-token authentication, and signed webhooks.
Base URL
https://api.yh-charter.com
Compliance
SOC 2 · PCI-DSS · GDPR
Sign up for a free developer account, generate a publishable/secret key pair, and make your first request in under sixty seconds. Every account begins in sandbox mode — no real reservations are created.
1
Register
Create your developer account and verify your email.
2
Get keys
Generate a publishable and secret key pair.
3
Call the API
List yachts with a single GET request.
curl https://api.yh-charter.com/v1/yachts \
-H "Authorization: Bearer sk_test_EXAMPLE_0000_not_a_real_key"The YH Charter API authenticates requests with Bearer tokens. Send your secret key in theAuthorizationheader. Treat secret keys like passwords — never commit them to version control, log them, or embed them in client-side code.
Keys prefixed with sk_test_ operate in the sandbox and only touch mock data. Use sk_live_ keys in production.
GET /v1/yachts HTTP/1.1
Host: api.yh-charter.com
Authorization: Bearer sk_live_EXAMPLE_1111_fake_placeholder
Accept: application/jsonPOST /v1/auth/token
Create an access token Exchange an API key pair for a short-lived Bearer token. Rotate tokens often for security; tokens expire after one hour.
Parameters
Name Type Required Description api_key string required Your publishable key (pk_...) secret string required Your secret key (sk_...) scope string[] optional Requested permissions (default: read)
Example response · 200 OK
{
"token": "eyJhbGc.EXAMPLE.token",
"expires_at": "2026-04-19T15:30:00Z",
"scope": ["read:yachts", "read:bookings"]
}DELETE /v1/auth/token
Revoke an access token Invalidate a token before its scheduled expiry. Useful when a device is lost or a compromise is suspected.
Parameters
Name Type Required Description Authorization header required Bearer <token>
Example response · 200 OK
DELETE /v1/auth/token {
"revoked": true,
"revoked_at": "2026-04-19T14:03:21Z"
}GET /v1/yachts
List yachts Return a paginated list of yachts. Combine query parameters to filter by destination, capacity, cabin count, or length class.
Parameters
Name Type Required Description destination string optional Region slug, e.g. amalfi-coast guests integer optional Minimum guest capacity limit integer optional Page size (1-100, default 25) cursor string optional Pagination cursor from previous response
Example response · 200 OK
{
"object": "list",
"has_more": true,
"data": [
{
"id": "yacht_EXAMPLE_ionian_spirit",
"object": "yacht",
"name": "Ionian Spirit",
"length_m": 48,
"guests_max": 12,
"cabins": 6,
"home_port": "Naples, IT",
"day_rate_eur": 18500
}
],
"next_cursor": "cur_EXAMPLE_next_page"
}GET /v1/yachts/{id}
Retrieve a yacht Return the complete profile for a single yacht, including cabin layout, crew roster, media gallery, and specification details.
Parameters
Name Type Required Description id string required The yacht identifier (yacht_...) expand string[] optional Comma-separated: crew,media,specs
Example response · 200 OK
{
"id": "yacht_EXAMPLE_ionian_spirit",
"object": "yacht",
"name": "Ionian Spirit",
"length_m": 48,
"guests_max": 12,
"crew_size": 9,
"amenities": ["jacuzzi", "jet_ski", "submarine_tender"],
"home_port": "Naples, IT"
}POST /v1/bookings
Create a booking Place a reservation for a selected yacht on given dates. Returns a booking object in the pending state until payment is captured.
Parameters
Name Type Required Description yacht_id string required Yacht identifier check_in ISO 8601 required Departure date check_out ISO 8601 required Return date guest_count integer required Number of guests aboard guest object required Primary guest contact object
Example response · 200 OK
{
"id": "book_EXAMPLE_abc123",
"object": "booking",
"status": "pending",
"total_eur": 129500,
"check_in": "2026-07-14",
"check_out": "2026-07-21"
}PUT /v1/bookings/{id}
Update a booking Adjust guest count, preferences, or add optional experiences to an existing booking. Dates are immutable once confirmed.
Parameters
Name Type Required Description id string required Booking identifier guest_count integer optional Revised guest count (not above yacht max) experiences string[] optional Optional experience IDs
Example response · 200 OK
PUT /v1/bookings/{id} {
"id": "book_EXAMPLE_abc123",
"object": "booking",
"status": "confirmed",
"updated_at": "2026-04-19T13:12:48Z"
}DELETE /v1/bookings/{id}
Cancel a booking Cancel an existing booking. Refunds are issued automatically according to the yacht cancellation policy.
Parameters
Name Type Required Description id string required Booking identifier reason string optional Free-text cancellation reason
Example response · 200 OK
DELETE /v1/bookings/{id} {
"id": "book_EXAMPLE_abc123",
"object": "booking",
"status": "cancelled",
"refund_eur": 64750
}GET /v1/availability
Check availability Return available date ranges for a yacht across a window. Useful for building calendars and booking widgets.
Parameters
Name Type Required Description yacht_id string required Yacht identifier start ISO 8601 required Start of search window end ISO 8601 required End of search window
Example response · 200 OK
{
"yacht_id": "yacht_EXAMPLE_ionian_spirit",
"windows": [
{ "start": "2026-07-01", "end": "2026-07-13" },
{ "start": "2026-07-22", "end": "2026-08-05" }
]
}GET /v1/guests
List guests Retrieve the guests attached to your account. Use the email filter to look up a single record or the segment query to build targeted campaigns.
Parameters
Name Type Required Description email string optional Case-insensitive equality match segment string optional vip | returning | new limit integer optional Page size (1-100, default 25)
Example response · 200 OK
{
"object": "list",
"has_more": false,
"data": [
{
"id": "gst_EXAMPLE_001",
"object": "guest",
"name": "Example Guest",
"email": "guest@example.test",
"segment": "vip",
"lifetime_value_eur": 412900
}
]
}POST /v1/quotes
Generate a quote Produce a priced quote for a hypothetical charter. Quotes are valid for 24 hours and can be converted directly into bookings.
Parameters
Name Type Required Description yacht_id string required Yacht identifier check_in ISO 8601 required Departure date check_out ISO 8601 required Return date guest_count integer required Number of guests currency string optional USD | EUR | GBP (default EUR)
Example response · 200 OK
{
"id": "qt_EXAMPLE_zyx987",
"object": "quote",
"yacht_id": "yacht_EXAMPLE_ionian_spirit",
"subtotal_eur": 118000,
"tax_eur": 11500,
"total_eur": 129500,
"expires_at": "2026-04-20T13:00:00Z"
}The API uses conventional HTTP response codes. Errors share a consistent envelope with a machine-readable code and a human-readable message.
Status Error code Meaning 400 bad_request The request payload was malformed or missing required fields. 401 unauthorized The request lacks valid authentication credentials. 403 forbidden The supplied token does not cover the requested scope. 404 not_found The requested resource could not be located. 409 conflict The state of the resource conflicts with the action. 422 unprocessable_entity Validation failed for one or more fields. 429 rate_limited You have exceeded the published rate limit. 500 server_error An unexpected condition was encountered. Try again shortly.
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header.",
"request_id": "req_EXAMPLE_0a1b2c3d4e"
}
}Register an HTTPS endpoint and receive signed events whenever something important changes — a booking is confirmed, a payment settles, or a quote expires. Each request includes an YH-Signature header containing an HMAC SHA-256 of the payload using your shared secret.
booking.createdbooking.confirmedbooking.cancelledpayment.capturedpayment.refundedquote.expiredRespond with 2xx within 10 seconds. Verify the signature before trusting the body. Idempotent handlers — retries are possible. Store the event.id for deduplication. POST /v1/webhooks
Register a webhook endpoint Tell YH Charter where to deliver events. The response includes a signing secret — rotate it any time from the API Keys dashboard.
{
"id": "wh_EXAMPLE_9f8e7d",
"object": "webhook",
"url": "https://example.test/hooks/yh",
"events": ["booking.confirmed", "payment.captured"],
"secret": "whsec_EXAMPLE_DO_NOT_USE"
}Hand-crafted libraries wrap every endpoint and the webhook signature helper. All four are MIT-licensed, versioned together, and released weekly.
npm install @yh-charter/nodeimport { YHCharter } from '@yh-charter/node';
const client = new YHCharter({
apiKey: process.env.YH_CHARTER_API_KEY, // sk_test_EXAMPLE_0000...
});
const yachts = await client.yachts.list({
destination: 'amalfi-coast',
guests: 10,
});
console.log(`Found ${yachts.data.length} yachts`);import yh_charter
yh_charter.api_key = "sk_test_EXAMPLE_0000_not_a_real_key"
yachts = yh_charter.Yacht.list(
destination="amalfi-coast",
guests=10,
)
print(f"Found {len(yachts.data)} yachts")require "yh_charter"
YhCharter.api_key = "sk_test_EXAMPLE_0000_not_a_real_key"
yachts = YhCharter::Yacht.list(
destination: "amalfi-coast",
guests: 10
)
puts "Found #{yachts.data.length} yachts"composer require yh-charter/yh-charter-php<?php
require_once 'vendor/autoload.php';
\YhCharter\Client::setApiKey('sk_test_EXAMPLE_0000_not_a_real_key');
$yachts = \YhCharter\Yacht::list([
'destination' => 'amalfi-coast',
'guests' => 10,
]);
printf("Found %d yachts\n", count($yachts->data));v1.8.0 latest April 11, 2026
Added `segment` filter to the List Guests endpoint. Webhooks now include a `livemode` boolean on every event. New SDK helper: `client.quotes.convert(quote_id)` for one-call booking. v1.7.2 patch March 02, 2026
Fixed a rare race condition in `/v1/availability` window merging. Added `X-Idempotency-Key` support to DELETE endpoints. v1.7.0 minor January 19, 2026
Introduced the Quotes resource with conversion into a booking. Rate limit raised to 2,000 requests per minute on paid plans. New webhook event: `quote.expired`. v1.6.0 minor November 04, 2025
Added `experiences` array to bookings. Deprecated `/v1/boats` alias — use `/v1/yachts` instead. v1.5.0 minor September 21, 2025
Launched signed webhook payloads using HMAC SHA-256. Added cursor-based pagination to List Yachts and List Guests. Get your API keys and ship in minutes. Sandbox is always free. Live keys unlock once your account completes KYB verification.