Data API
Reference

API Reference

A small, read-only REST API over the canonical YachtMaster make / model / engine taxonomy. JSON in, JSON out, versioned under /v1.

Base URL https://data.yachtmaster.cloud

Introduction

Every make, model, engine and drive is keyed on a stable YachtMaster id — the identifier you store and build against. Names on makes and models are plain strings; lookup enums (fuels, engine types, materials, object types) carry multilingual names. Published rows also carry the editorial content behind the public boat wiki — specs, descriptions, sources and reviews, covered under Editorial content below. The data is maintained for you and refreshed weekly.

Authentication

Send your key as a bearer token on every request:

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/makes

Create, reveal, rotate or revoke keys from your dashboard. Keep keys server-side — they carry your billing.

Conventions

Pagination. List endpoints return { data, page, page_size, has_more }. Use page and page_size (max 1000).
Incremental sync. Pass updated_since=<ISO 8601> to fetch only what changed — ideal for keeping a local copy fresh.
Caching. Responses carry an ETag; send it back as If-None-Match to get a cheap 304 Not Modified.
Forward-compatible. New fields are added without notice — ignore unknown ones. Breaking changes ship under a new version path.
Localization. Lookup and object-type names are returned as a name object keyed by language. Fuels, engine types and object types carry all 8 — de, en, es, fi, fr, it, lt, sv; materials currently carry only en, fi, sv.

Editorial content

Beyond the identity columns, makes, models, engine makes, engine models and drives now also carry the editorial content behind the public boat wiki — descriptions, specs, sources and reviews. A few things are worth understanding before you build against it.

Specs are an open object. Keys carry their unit in the name and hold bare numbers — length_m: 8.0, never "8.0 m" — which is what keeps comparison and filtering possible. Typical boat keys: length_m, beam_m, draft_m, weight_kg, fuel_l, water_l, berths, cabins, ce_category. Engine keys: power_hp, power_kw, cylinders, displacement_l, aspiration, configuration. The vocabulary grows over time — tolerate keys you don't recognise.
Some values are ranges. berths: [4, 6] means the model ships in two layouts. A model describes a class of boat, not one hull, so a range is the honest answer.
Ids resolve against lookups. material_id → /v1/lookups/materials, fuel_id → /v1/lookups/fuels, engine_type_id → /v1/lookups/engine-types. You get an id rather than a string so you can join once and render in your own language.
description and summary are objects, not strings — { "en": "…" }. Only en is populated today; more languages can land later without a breaking change, which is exactly why they're keyed objects rather than plain text.
Unpublished rows come back as identity only. Editorial fields are populated once a row is published, and null otherwise — you'll see id, name and the parent id with every editorial field null, and on the detail endpoints, empty child lists. Treat a null field as "not available yet," not as "this boat has no length."

Endpoints

GET /v1/object-types

List the vehicle classes (motorboat, sailingboat, car, campervan, jetski …) with multilingual names in de, en, es, fi, fr, it, lt, sv.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/object-types

[
  {
    "id": 1,
    "name": {
      "de": "Motorboot",
      "en": "Motorboat",
      "es": "Motora",
      "fi": "Moottorivene",
      "fr": "Bateau à moteur",
      "it": "Barca a Motore",
      "lt": "motorinė valtis",
      "sv": "Motorbåt"
    }
  }
]

GET /v1/makes

List makes. Filterable by object type, paginated, with model counts. Editorial fields are populated once a make is published, and null otherwise. Make rows that marketplaces list under a vehicle class the builder doesn’t build for — a motorboat yard among sailboats — are left out; their ids still resolve on GET /v1/makes/{id}.

object_type	integer	Filter to one vehicle class (e.g. 1 = motorboat).
updated_since	ISO 8601	Only makes changed after this timestamp.
page	integer	Page number, default 1.
page_size	integer	1–1000, default 100.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/makes?object_type=1&page_size=2

{
  "data": [
    {
      "id": 1,
      "object_type_id": 1,
      "name": "Aaltomarine",
      "model_count": 1,
      "updated_at": "2026-07-06T06:34:29Z",
      "slug": null,
      "country_code": null,
      "founded_year": null,
      "defunct_year": null,
      "hq_city": null,
      "website_url": null,
      "slogan": null,
      "description": null
    },
    {
      "id": 2,
      "object_type_id": 1,
      "name": "AB",
      "model_count": 1,
      "updated_at": "2026-07-06T06:34:29Z",
      "slug": null,
      "country_code": null,
      "founded_year": null,
      "defunct_year": null,
      "hq_city": null,
      "website_url": null,
      "slogan": null,
      "description": null
    }
  ],
  "page": 1,
  "page_size": 2,
  "has_more": true
}

Neither make is published yet, so the widened fields all come back null — see GET /v1/makes/{id} below for a published one.

GET /v1/makes/resolve

Turn a free-text make name into canonical make ids. Case-insensitive substring match — "benet" finds Beneteau — best match first, up to 5.

name	string	Required. The make name, or part of it.
object_type	integer	Only makes in this vehicle class.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/makes/resolve?name=buster

[
  {
    "id": 96,
    "object_type_id": 1,
    "name": "Buster"
  }
]

GET /v1/makes/{id}

A single make by YachtMaster id, with its model count and — once published — its slug, founding facts, homepage and description. 404s only if the id itself is unknown.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/makes/3182

{
  "id": 3182,
  "object_type_id": 1,
  "name": "Sargo",
  "model_count": 9,
  "updated_at": "2026-08-10T09:15:22Z",
  "slug": "sargo",
  "country_code": "FI",
  "founded_year": 1979,
  "defunct_year": null,
  "hq_city": "Kokkola",
  "website_url": "https://sargoboats.com",
  "slogan": "All-weather boats",
  "description": {
    "en": "Sargo Boats builds aluminium motorboats engineered for the demanding conditions of the Nordic archipelago."
  }
}

GET /v1/makes/{id}/models

Models for a make, paginated, with editorial content once each model is published. Marketplace “other model” placeholders (Muu malli), models filed under the wrong vehicle class and engine codes listed as boats are not listed; their ids still resolve on GET /v1/models/{id}.

updated_since	ISO 8601	Only models changed after this timestamp.
page	integer	Page number, default 1.
page_size	integer	1–1000, default 100.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/makes/771/models?page_size=3

{
  "data": [
    {
      "id": 3070,
      "make_id": 771,
      "name": "50",
      "updated_at": "2026-07-06T06:38:06Z",
      "slug": null,
      "specs": null,
      "production_start_year": null,
      "production_end_year": null,
      "variants": null,
      "designer": null,
      "material_id": null
    },
    {
      "id": 3071,
      "make_id": 771,
      "name": "550 Cabin",
      "updated_at": "2026-07-06T06:38:06Z",
      "slug": null,
      "specs": null,
      "production_start_year": null,
      "production_end_year": null,
      "variants": null,
      "designer": null,
      "material_id": null
    },
    {
      "id": 3072,
      "make_id": 771,
      "name": "Antares",
      "updated_at": "2026-07-06T06:38:06Z",
      "slug": null,
      "specs": null,
      "production_start_year": null,
      "production_end_year": null,
      "variants": null,
      "designer": null,
      "material_id": null
    }
  ],
  "page": 1,
  "page_size": 3,
  "has_more": true
}

None of Beneteau’s models are published yet, so every widened field is null — compare with GET /v1/models/{id} below.

Walkthrough — makes → models

List makes for an object type — each entry carries a model_count. Beneteau (id: 771) reports model_count: 52, so drill in with GET /v1/makes/771/models to page through its 52 models. The make id from step one is simply the path parameter in step two — no lookups needed in between.

GET /v1/models/resolve

Turn a free-text boat name — say, from a listing — into canonical model ids. Searches every model in the taxonomy, published or not. Every word must appear in the make or model name, in any order, so "buster magnum", "magnum buster" and "magnum" all match. Best match first.

name	string	Required. Make and/or model words.
make_id	integer	Only models of this make.
object_type	integer	Only models in this vehicle class.
limit	integer	1–25, default 5.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/models/resolve?name=buster%20magnum&limit=3

[
  {
    "id": 491,
    "make_id": 96,
    "make_name": "Buster",
    "object_type_id": 1,
    "name": "Magnum E"
  },
  {
    "id": 492,
    "make_id": 96,
    "make_name": "Buster",
    "object_type_id": 1,
    "name": "Magnum M5"
  },
  {
    "id": 493,
    "make_id": 96,
    "make_name": "Buster",
    "object_type_id": 1,
    "name": "Magnum Pro"
  }
]

Each match carries its make name, so you can tell apart models that share a name across makes.

GET /v1/models/search

Filter models by specification. Only published models are searched — specs exist once a model has been researched, so this covers a growing part of the catalogue, not all of it. A model without a given spec never matches a filter on that spec. Repeat a list filter to OR its values; different filters are AND-ed.

length_min, length_max	number	Length in metres. Same pattern for beam_m (beam_), draft_m (draft_), weight_kg (weight_), fuel_l (fuel_), water_l (water_), max_hp (max_hp_), sail_area_m2 (sail_area_) and ballast_kg (ballast_).
berths_min, cabins_min, toilets_min	integer	Matches ranges too: berths_min=4 matches a model offered with [2, 5].
year_min, year_max	integer	Production period overlap. A model still in production is open-ended.
body_type	string, repeatable	cabin, walkaround, pilothouse, open, bowrider, center_console, rib, flybridge, motor_yacht, cruiser, daysailer, cruiser_racer, catamaran, motorsailer, dinghy.
propulsion	string, repeatable	sterndrive, outboard, shaft, pod, jet, surface.
make_id, material_id, object_type	integer, repeatable	Only these makes, hull materials or vehicle classes.
sort	string	name (make, then model), length or year; prefix - for descending. Default name.
page	integer	Page number, default 1.
page_size	integer	1–100, default 24.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/models/search?length_min=10&length_max=12&body_type=cabin&sort=length&page_size=2

{
  "data": [
    {
      "id": 91,
      "make_id": 35,
      "name": "33 HT",
      "updated_at": "2026-09-07T03:01:42Z",
      "slug": "aquador-33-ht",
      "specs": {
        "length_m": 10,
        "beam_m": 3.45,
        "weight_kg": 5000,
        "berths": 8,
        "body_type": [
          "cabin"
        ]
      },
      "production_start_year": null,
      "production_end_year": null,
      "variants": null,
      "designer": null,
      "material_id": null
    },
    {
      "id": 4207,
      "make_id": 1291,
      "name": "3400 Europe",
      "updated_at": "2026-09-07T03:04:01Z",
      "slug": "nimbus-3400-europe",
      "specs": {
        "length_m": 10,
        "beam_m": 3.45,
        "draft_m": 1,
        "fuel_l": 600,
        "water_l": 250,
        "max_hp": 400,
        "berths": 6,
        "cabins": 3,
        "body_type": [
          "motor_yacht",
          "cabin"
        ],
        "propulsion": [
          "shaft"
        ]
      },
      "production_start_year": 1988,
      "production_end_year": null,
      "variants": null,
      "designer": "Rolf Eliasson",
      "material_id": 2
    }
  ],
  "page": 1,
  "page_size": 2,
  "has_more": true,
  "total": 25
}

Unlike the list endpoints, search also returns total — the number of matching models across all pages.

GET /v1/models/{id}

A single model by YachtMaster id: specs, production years, variants and designer, plus its engine options, sources and reviews. A model that isn’t published yet — unresearched or mid-review — returns 200 with just the identity columns: every editorial field null, every list empty. 404 means the id is unknown, or belongs to a model our research has added but not yet published.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/models/4521

{
  "id": 4521,
  "make_id": 3182,
  "name": "36",
  "updated_at": "2026-08-05T10:02:00Z",
  "slug": "sargo-36",
  "specs": {
    "length_m": 11.35,
    "beam_m": 3.5,
    "draft_m": 0.95,
    "weight_kg": 8200,
    "fuel_l": 1000,
    "water_l": 200,
    "berths": [
      4,
      6
    ],
    "cabins": 2,
    "ce_category": "B"
  },
  "production_start_year": 2018,
  "production_end_year": null,
  "variants": "Cabin, Coupe",
  "designer": null,
  "material_id": 2,
  "summary": {
    "en": "A twin-diesel aluminium cruiser built for open-water passages."
  },
  "description": {
    "en": "The Sargo 36 pairs an all-weather aluminium hull with an enclosed pilothouse and twin Volvo Penta diesels."
  },
  "engine_options": [
    {
      "engine_model_id": 819,
      "engine_make_id": 12,
      "engine_label": "Volvo Penta D6-400",
      "quantity": 2,
      "years": "2018–"
    }
  ],
  "sources": [
    {
      "url": "https://sargoboats.com/36/specs.pdf",
      "kind": "spec_sheet",
      "title": "Sargo 36 Technical Specification",
      "publisher": "Sargo Boats"
    }
  ],
  "reviews": [
    {
      "url": "https://batliv.se/sargo-36-test",
      "kind": "review",
      "platform": null,
      "publisher": "Båtliv",
      "author": "Erik Nilsson",
      "title": "Sargo 36 — sjötest",
      "published_at": "2023-06-02"
    }
  ]
}

`berths: [4, 6]` is a range — the 36 ships in two layouts. `material_id` resolves against GET /v1/lookups/materials.

GET /v1/engine-makes

List engine makes with model counts, paginated. Editorial fields are populated once an engine make is published, and null otherwise.

updated_since	ISO 8601	Only engine makes changed after this timestamp.
page	integer	Page number, default 1.
page_size	integer	1–1000, default 100.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/engine-makes?page_size=2

{
  "data": [
    {
      "id": 1,
      "name": "Abini",
      "model_count": 0,
      "updated_at": "2025-04-29T04:18:28Z",
      "slug": null,
      "country_code": null,
      "founded_year": null,
      "website_url": null,
      "summary": null,
      "description": null
    },
    {
      "id": 2,
      "name": "Albin",
      "model_count": 0,
      "updated_at": "2025-04-29T04:18:28Z",
      "slug": null,
      "country_code": null,
      "founded_year": null,
      "website_url": null,
      "summary": null,
      "description": null
    }
  ],
  "page": 1,
  "page_size": 2,
  "has_more": true
}

GET /v1/engine-makes/{id}/models

Engine models for an engine make, paginated, with editorial content once each engine model is published: specs, fuel, mount, stroke, engine type.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/engine-makes/1/models

{
  "data": [
    {
      "id": 501,
      "engine_make_id": 1,
      "name": "9.9 FourStroke",
      "updated_at": "2025-04-29T04:18:28Z",
      "slug": null,
      "specs": null,
      "fuel_id": null,
      "mount": null,
      "stroke": null,
      "engine_type_id": null,
      "production_start_year": null,
      "production_end_year": null,
      "variants": null
    }
  ],
  "page": 1,
  "page_size": 100,
  "has_more": false
}

Engine-model coverage is still expanding — some engine makes currently return an empty data array.

GET /v1/engine-makes/{id}/drives

Drives for an engine make, paginated — pods, sterndrive legs, gearboxes. `name` and `kind` are always present; `slug` is populated once the drive is published.

updated_since	ISO 8601	Only drives changed after this timestamp.
page	integer	Page number, default 1.
page_size	integer	1–1000, default 100.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/engine-makes/12/drives

{
  "data": [
    {
      "id": 301,
      "engine_make_id": 12,
      "name": "IPS500",
      "kind": "pod",
      "slug": "volvo-penta-ips500",
      "updated_at": "2026-08-09T12:00:00Z"
    },
    {
      "id": 302,
      "engine_make_id": 12,
      "name": "IPS600",
      "kind": "pod",
      "slug": null,
      "updated_at": "2026-08-09T12:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 100,
  "has_more": false
}

GET /v1/engine-models/resolve

Turn a free-text engine name into canonical engine model ids. Every word must appear in the engine make or model name, in any order, so "volvo penta d6 440" matches D6-440. Best match first.

name	string	Required. Engine make and/or model words.
engine_make_id	integer	Only engine models of this engine make.
limit	integer	1–25, default 5.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/engine-models/resolve?name=volvo%20penta%20d6%20440

[
  {
    "id": 10,
    "engine_make_id": 117,
    "engine_make_name": "Volvo Penta",
    "name": "D6-440"
  }
]

GET /v1/engine-models/{id}

A single engine model by YachtMaster id, with its editorial content, sources, reviews and `fitted_in` — the boats it’s offered in, deduplicated. Same publish rules as GET /v1/models/{id}.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/engine-models/819

{
  "id": 819,
  "engine_make_id": 12,
  "name": "D6-400",
  "updated_at": "2026-08-09T12:00:00Z",
  "slug": "volvo-penta-d6-400",
  "specs": {
    "power_hp": 400,
    "power_kw": 294,
    "cylinders": 6,
    "displacement_l": 5.5,
    "aspiration": "turbocharged",
    "configuration": "inline"
  },
  "fuel_id": 2,
  "mount": "inboard",
  "stroke": null,
  "engine_type_id": null,
  "production_start_year": 2018,
  "production_end_year": null,
  "variants": null,
  "summary": {
    "en": "A 5.5-litre inline-six diesel for planing and semi-displacement hulls."
  },
  "description": {
    "en": "The D6-400 is Volvo Penta’s workhorse inboard diesel, offered on shaft, sterndrive and IPS pod drives."
  },
  "sources": [
    {
      "url": "https://volvopenta.com/marine-leisure/engines/d6/",
      "kind": "spec_sheet",
      "title": "D6-400 Technical Specification",
      "publisher": "Volvo Penta"
    }
  ],
  "reviews": [],
  "fitted_in": [
    {
      "id": 4521,
      "make_id": 3182,
      "name": "36"
    }
  ]
}

`engine_type_id` is null on purpose — the D6-400 is a general-purpose block, and its drive (shaft, sterndrive, IPS) is a pairing choice, not a fact about the engine. `stroke` is null too: it only applies to outboards.

GET /v1/drives/{id}

`name` and `kind` are always present; `slug`, `summary`, `description` and `sources` are populated once the drive is published — same publish rules as GET /v1/models/{id}, except a mid-review drive still returns its name and kind.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/drives/301

{
  "id": 301,
  "engine_make_id": 12,
  "name": "IPS500",
  "kind": "pod",
  "slug": "volvo-penta-ips500",
  "updated_at": "2026-08-09T12:00:00Z",
  "summary": {
    "en": "Volvo Penta’s forward-facing pod drive, paired with the D6 diesel range."
  },
  "description": {
    "en": "IPS500 turns twin forward-facing, contra-rotating props to pull rather than push the boat through the water."
  },
  "sources": [
    {
      "url": "https://volvopenta.com/marine-leisure/ips/ips500",
      "kind": "spec_sheet",
      "title": "IPS500 Technical Specification",
      "publisher": "Volvo Penta"
    }
  ]
}

GET /v1/lookups/fuels

Fuel types with multilingual names in de, en, es, fi, fr, it, lt, sv.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/lookups/fuels

[
  {
    "id": 1,
    "name": {
      "de": "Benzin",
      "en": "Petrol",
      "es": "Gasolina",
      "fi": "Bensiini",
      "fr": "Essence",
      "it": "Benzina",
      "lt": "Benzinas",
      "sv": "Bensin"
    }
  },
  {
    "id": 2,
    "name": {
      "en": "Diesel",
      "fi": "Diesel",
      "sv": "Diesel",
      "de": "Diesel"
    }
  }
]

Translation coverage varies per entry — a name object may carry fewer than 8 keys until all languages are confirmed.

GET /v1/lookups/engine-types

Engine types with multilingual names in de, en, es, fi, fr, it, lt, sv.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/lookups/engine-types

[
  {
    "id": 1,
    "name": {
      "en": "Outboard 4-stroke",
      "fi": "Perämoottori 4-tahti",
      "sv": "Utombordare 4-takt",
      "de": "Außenborder 4-Takt"
    }
  }
]

GET /v1/lookups/materials

Hull materials — resolves a model's material_id. Multilingual names in en, fi, sv only, a smaller set than the other lookups.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/lookups/materials

[
  {
    "id": 1,
    "name": {
      "en": "GRP",
      "fi": "Lasikuitu",
      "sv": "Glasfiber"
    }
  },
  {
    "id": 2,
    "name": {
      "en": "Aluminium",
      "fi": "Alumiini",
      "sv": "Aluminium"
    }
  }
]

GET /v1/dump

The entire taxonomy skeleton in one response — object types, makes, models, engine makes, engine models and lookups, identity columns only. No editorial content and no drives. Ideal for a periodic full sync.

Example response

curl -H "Authorization: Bearer ymk_your_key" \
  https://data.yachtmaster.cloud/v1/dump

{ "object_types": [ /* 12 */ ], "makes": [ /* 3364 */ ], "models": [ /* 12838 */ ],
  "engine_makes": [ /* 129 */ ], "engine_models": [ /* … */ ],
  "fuels": [ /* 5 */ ], "engine_types": [ /* 7 */ ] }

A large payload, and identity-only by design — no specs, no drives. Most integrations poll updated_since on the individual endpoints instead and reserve /v1/dump for the initial seed; page the per-resource endpoints for enrichment.

Errors

Errors return a JSON body with a detail message and the status below.

401	Missing or invalid API key.
402	Subscription inactive — reactivate billing to resume.
404	No resource with that id.
422	Invalid query parameter — the response body names it.
429	Rate limit exceeded — slow down and retry.

Rate limits

Your plan includes 100,000 requests per month; usage beyond that is billed at €1 per additional 10,000. A per-key rate limit (a few requests per second) guards against abuse — well above what a cache-and-sync integration needs. If you hit it, back off and retry on 429.

Prefer an interactive reference? The full OpenAPI spec and a live “try it” console are always in sync with the API.

Open the live API console