Developers
API and webhooks
Workspace owners and admins create scoped API keys and webhooks under Workspace → API and webhooks.
Authentication
Send the key as a bearer token. Keys act for one workspace and only for the scopes chosen; admin endpoints are never available to keys.
curl -H "Authorization: Bearer ya_xxxxxxxxxxxx_…" https://yachtsads.com/api/v1/listings
Scopes: listings:read, listings:write, inventory:read, inventory:write, requests:read, requests:write, vessels:read. A missing scope returns 403 insufficient_scope; an unknown or revoked key returns 401.
Errors use one format: {"error": {"code", "message", "fields", "trace_id"}}. Requests are rate limited per key.
Endpoints (v1)
The full machine-readable description is in OpenAPI 3.1 format: /api/v1/openapi.json. “session” endpoints work only for signed-in users, not for API keys.
| Endpoint | What it does | Scope |
|---|---|---|
GET /api/v1/me | The signed-in user, the active workspace and the workspaces the user belongs to | any |
POST /api/v1/workspaces/switch | Switch the active workspace (session sign-in only) | session |
GET /api/v1/vessels | Vessels the active workspace can access (cursor pagination: limit 1–100, cursor) | vessels:read |
POST /api/v1/vessels | Register a vessel (session sign-in only) | session |
GET /api/v1/vessels/{id} | One vessel the workspace holds an access grant for | vessels:read |
PATCH /api/v1/vessels/{id} | Update a vessel (optimistic locking with version; session sign-in only) | session |
GET /api/v1/listing-types | Listing types with their categories, price types and attributes | public |
GET /api/v1/listings | Listings of the active workspace (optional status filter) | listings:read |
POST /api/v1/listings | Create a draft listing | listings:write |
GET /api/v1/listings/changes | Changes to the workspace's listings since a cursor (feed for partners) | listings:read |
GET /api/v1/listings/{id} | One listing of the workspace with its status, authority and history | listings:read |
PATCH /api/v1/listings/{id} | Update a listing (optimistic locking with version) | listings:write |
POST /api/v1/listings/{id}/transitions | Submit, pause, resume, mark sold, withdraw or renew (see available_actions) | listings:write |
POST /api/v1/listings/{id}/authority | Declare the authority to sell (signer and role) | listings:write |
POST /api/v1/listings/{id}/authority/decision | Decide an authority declaration (staff) | listings:write |
GET /api/v1/search | Public search of yachts for sale (same filters as /yachts-for-sale; type=yacht_sale) | public |
GET /api/v1/inventory | Stock items of the supplier workspace | inventory:read |
POST /api/v1/inventory/{id}/reservations | Reserve stock of an item | inventory:write |
POST /api/v1/inventory/sync | Update stock and price of up to 500 existing SKUs; returns a result per SKU | inventory:write |
GET /api/v1/requests | Requests for quotes the workspace sent or was invited to | requests:read |
POST /api/v1/requests | Create a request for quotes (draft) | requests:write |
GET /api/v1/requests/{id} | One request with its participants and quotes | requests:read |
POST /api/v1/requests/{id}/invitations | Invite providers by workspace id | requests:write |
POST /api/v1/requests/{id}/open | Open a draft request to the invited providers | requests:write |
POST /api/v1/requests/{id}/quotes | Submit or revise the provider's quote | requests:write |
POST /api/v1/requests/{id}/quotes/withdraw | Withdraw the provider's quote | requests:write |
POST /api/v1/requests/{id}/decline | Decline the invitation (provider) | requests:write |
POST /api/v1/requests/{id}/fulfil | Mark the accepted request fulfilled | requests:write |
POST /api/v1/requests/{id}/cancel | Cancel the request with a reason | requests:write |
POST /api/v1/quotes/{id}/accept | Accept a quote version (buyer) | requests:write |
POST /api/v1/uploads | Start a resumable upload of a vessel document (session sign-in only) | session |
PUT /api/v1/uploads/{id}/chunks/{n} | Upload chunk n (raw bytes in the body) | session |
GET /api/v1/uploads/{id} | Upload status and received chunks | session |
POST /api/v1/uploads/{id}/complete | Assemble the chunks, verify the checksum and store the file | session |
Inventory sync body: {"items": [{"sku": "VP-1", "on_hand": 4, "price": "395.00"}]} — up to 500 SKUs, existing items only, result per SKU
Webhooks
Events caused by your workspace are POSTed as JSON to your https endpoint: ListingPublished, ListingSold, ListingClosed, ListingExpired, ListingPriceChanged, QuoteSubmitted, QuoteAccepted, ServiceOrderClosed, CharterBookingConfirmed, PaymentSucceeded, RefundSucceeded, BerthReserved, ShipmentUpdated.
Verify X-YachtsAds-Signature: t=<unix>,v1=<hex> as HMAC-SHA256 of “t.body” with your signing secret, reject old timestamps, and de-duplicate on X-YachtsAds-Delivery. Non-2xx responses are retried with exponential backoff (8 attempts); failed deliveries can be retried from the dashboard.