# Yachtworld — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse thousands of boat listings on YachtWorld by make, class, type, condition, location, and price range. Retrieve detailed specifications, propulsion data, media assets, and broker contact information for any listing.

**Category:** Marketplaces | **Website:** [yachtworld.com/](https://yachtworld.com/) | **Docs:** [parse.bot/marketplace/0f99aef8-53d0-420a-a582-618e19136492/yachtworld-com-api](https://parse.bot/marketplace/0f99aef8-53d0-420a-a582-618e19136492/yachtworld-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/yachtworld/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get boat detail

Retrieve full detailed information for a single boat listing by its numeric ID. Returns comprehensive data including specs, description, media, propulsion, pricing, contact info, and location. The detail response includes fields not present in search results such as full engine specifications, tank capacities, hull details, and multilingual descriptions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `boat_id` | string | Yes | Numeric boat listing ID (e.g., '9858107'). Available from search results as the id field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/get-boat-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"boat_id":"<string>"}'
```

### Get boat types

Retrieve the taxonomy of boat classes available on YachtWorld. Returns an array of class objects with value slugs, display names, counts, and heading categories. Useful for discovering valid class values to pass to search_boats_by_class.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/get-boat-types \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get broker listings

Retrieve all active boat listings for a specific yacht broker/dealer by their owner ID. Returns paginated results with the same structure as search_boats_for_sale.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `owner_id` | string | Yes | Broker/dealer owner ID (numeric string). Available from listing data or broker profile pages. |
| `page` | integer | No | Page number (1-based) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/get-broker-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","owner_id":"<string>","page":"<integer>"}'
```

### Search boats by class

List boats for sale filtered by boat class. Class values include type prefix (e.g., 'power-center', 'sail-cruiser'). Returns paginated results with the same structure as search_boats_for_sale.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `class` | string | Yes | Boat class slug with type prefix (e.g., 'power-center', 'sail-cruiser', 'power-motor', 'power-pontoon'). Use get_boat_types to see all available values. |
| `limit` | integer | No | Results per page |
| `page` | integer | No | Page number (1-based) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/search-boats-by-class \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"class":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Search boats by make

List boats for sale filtered by a specific manufacturer/make. Returns paginated results with the same structure as search_boats_for_sale including sponsored listings, facets, and ordered result records.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page |
| `make` | string | Yes | Boat manufacturer name (e.g., 'Beneteau', 'Sea Ray', 'Boston Whaler') |
| `page` | integer | No | Page number (1-based) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/search-boats-by-make \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","make":"<string>","page":"<integer>"}'
```

### Search boats for sale

Search for boats for sale with comprehensive filters including make, type, class, condition, location, price range, and year range. Returns paginated results with sponsored listings, facets for filtering, and ordered result records. Paginates via integer page number. Each result record contains listing summary data (id, make, model, year, price, location, media). Facets provide counts for available filter values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `class` | string | No | Boat class slug (e.g., 'power-center', 'sail-cruiser', 'power-motor'). Use get_boat_types to see available values. |
| `condition` | string | No | Boat condition filter. |
| `country` | string | No | Country code (e.g., 'US', 'GB', 'IT') |
| `facets` | string | No | Additional raw facet string to append |
| `fuel_type` | string | No | Fuel type filter. |
| `limit` | integer | No | Results per page |
| `make` | string | No | Boat manufacturer name (e.g., 'Beneteau', 'Sea Ray') |
| `owner_id` | string | No | Broker/dealer owner ID to filter listings by a specific dealer |
| `page` | integer | No | Page number (1-based) |
| `price_max` | integer | No | Maximum price in USD |
| `price_min` | integer | No | Minimum price in USD |
| `sort` | string | No | Sort order for results. |
| `type` | string | No | Boat type filter. |
| `year_max` | integer | No | Maximum model year |
| `year_min` | integer | No | Minimum model year |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yachtworld/search-boats-for-sale \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"class":"<string>","condition":"<string>","country":"<string>","facets":"<string>","fuel_type":"<string>","limit":"<integer>","make":"<string>","owner_id":"<string>","page":"<integer>","price_max":"<integer>","price_min":"<integer>","sort":"<string>","type":"<string>","year_max":"<integer>","year_min":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.