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.

EndpointWhat it doesScope
GET /api/v1/meThe signed-in user, the active workspace and the workspaces the user belongs toany
POST /api/v1/workspaces/switchSwitch the active workspace (session sign-in only)session
GET /api/v1/vesselsVessels the active workspace can access (cursor pagination: limit 1–100, cursor)vessels:read
POST /api/v1/vesselsRegister a vessel (session sign-in only)session
GET /api/v1/vessels/{id}One vessel the workspace holds an access grant forvessels:read
PATCH /api/v1/vessels/{id}Update a vessel (optimistic locking with version; session sign-in only)session
GET /api/v1/listing-typesListing types with their categories, price types and attributespublic
GET /api/v1/listingsListings of the active workspace (optional status filter)listings:read
POST /api/v1/listingsCreate a draft listinglistings:write
GET /api/v1/listings/changesChanges 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 historylistings:read
PATCH /api/v1/listings/{id}Update a listing (optimistic locking with version)listings:write
POST /api/v1/listings/{id}/transitionsSubmit, pause, resume, mark sold, withdraw or renew (see available_actions)listings:write
POST /api/v1/listings/{id}/authorityDeclare the authority to sell (signer and role)listings:write
POST /api/v1/listings/{id}/authority/decisionDecide an authority declaration (staff)listings:write
GET /api/v1/searchPublic search of yachts for sale (same filters as /yachts-for-sale; type=yacht_sale)public
GET /api/v1/inventoryStock items of the supplier workspaceinventory:read
POST /api/v1/inventory/{id}/reservationsReserve stock of an iteminventory:write
POST /api/v1/inventory/syncUpdate stock and price of up to 500 existing SKUs; returns a result per SKUinventory:write
GET /api/v1/requestsRequests for quotes the workspace sent or was invited torequests:read
POST /api/v1/requestsCreate a request for quotes (draft)requests:write
GET /api/v1/requests/{id}One request with its participants and quotesrequests:read
POST /api/v1/requests/{id}/invitationsInvite providers by workspace idrequests:write
POST /api/v1/requests/{id}/openOpen a draft request to the invited providersrequests:write
POST /api/v1/requests/{id}/quotesSubmit or revise the provider's quoterequests:write
POST /api/v1/requests/{id}/quotes/withdrawWithdraw the provider's quoterequests:write
POST /api/v1/requests/{id}/declineDecline the invitation (provider)requests:write
POST /api/v1/requests/{id}/fulfilMark the accepted request fulfilledrequests:write
POST /api/v1/requests/{id}/cancelCancel the request with a reasonrequests:write
POST /api/v1/quotes/{id}/acceptAccept a quote version (buyer)requests:write
POST /api/v1/uploadsStart 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 chunkssession
POST /api/v1/uploads/{id}/completeAssemble the chunks, verify the checksum and store the filesession

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.