Public API

A read-only REST API over TheBoatDB's catalogue: every boat model and manufacturer we publish, with filtering, sorting and pagination. Responses are JSON, versioned under /v1, and shaped by us — you are not querying our CMS, so the fields you build against do not move when our content model does.

Every endpoint is served from https://api.theboatdb.com.

What you can read

Everything is GET. There is no write surface — the catalogue is editorial, and corrections go through us rather than through the API.

Before you start

You need an active Pro subscription and an API key. Keys are self-service:

1. Sign in and open API keys in your dashboard.
2. Create a key and give it a name you will recognise in six months ("staging importer", not "key 2").
3. Copy it. The full key is shown once, at creation — after that we only ever show you a prefix.

If you do not have a Pro subscription yet, compare the plans.

Your first request

curl -s "https://api.theboatdb.com/v1/boats?limit=2" \
-H "Authorization: Bearer $THEBOATDB_API_KEY"

A successful list response looks like this — a data array and a pagination object, on every list endpoint without exception:

{
  "data": [
    {
      "id": "boat-3f9c1a",
      "slug": "albin-vega-27",
      "model": "Vega 27",
      "version": null,
      "manufacturer": {
        "id": "mfr-71b0",
        "name": "Albin Marine",
        "slug": "albin-marine",
        "website": "https://example.com"
      },
      "type": { "id": "type-sail", "name": "Sail", "slug": "sail" },
      "production": { "firstYear": 1966, "lastYear": 1979 },
      "unit": "metric",
      "lengthOverall": 8.25,
      "lengthOverallMetres": 8.25,
      "referencePrice": null,
      "image": { "url": "https://cdn.sanity.io/...", "alt": null, "width": 1600, "height": 1067, "format": "jpg" }
    }
  ],
  "pagination": { "total": 1482, "limit": 2, "offset": 0 }
}

Fetching one boat returns the full record under data, with the manufacturer, type, hull type and categories expanded inline:

curl -s "https://api.theboatdb.com/v1/boats/albin-vega-27" \
-H "Authorization: Bearer $THEBOATDB_API_KEY"

Try it without writing any code

Every endpoint is also callable from the browser in the API explorer: paste your key into the authentication box and send a real request. It is the fastest way to see the response shape before you write against it. See OpenAPI reference.

Verifying your setup

GET /v1 is unauthenticated and returns the version descriptor. If that responds but your authenticated calls do not, the problem is the key, not the network:

curl -s https://api.theboatdb.com/v1

GET /health is a plain uptime check, also unauthenticated. Neither counts against your rate limit.

Where to go next

• Authentication — scopes, test vs live keys, and what each failure means.
• Conventions — the envelope, pagination and sorting rules shared by every endpoint.
• Errors — the full error-code table, and which ones are worth retrying.
• Rate limits — your monthly quota and per-minute limit, the headers on every response, and how to back off.
• Boats and Manufacturers — the endpoint reference.
• Versioning — what /v1 guarantees, and how much notice a breaking change gets.
• OpenAPI reference — the machine-readable spec, and generating a client from it.