OpenAPI reference

Everything on these pages is also published as a machine-readable OpenAPI 3.1 document.

Both are public. You do not need a key to read them — you need one to make a call.

Try a request in the browser

The API explorer has a Test Request panel on every endpoint. Paste your own key into the authentication box, choose an endpoint, and it calls the real API from your browser and shows you the real response.

The document is generated, not written

The spec is built from the same Zod schemas the service validates requests against and constructs responses from. A parameter's bounds in the document are the bounds that actually reject a bad request; a response field is in the document because the code returns it.

Practically, that means:

• It cannot silently fall behind the API. The API's build fails if an endpoint exists without appearing in the document, if the document describes one that does not exist, or if the copy published here is not the one the current schemas produce.
• It is the first place a change appears — before this prose, and before any announcement. See Versioning.
• Response schemas are deliberately open. They do not set additionalProperties: false, because adding a field is a change we reserve the right to make. Generate your client accordingly.

Generating a client

npx openapi-typescript https://theboatdb.com/docs/api/openapi.json -o src/theboatdb.d.ts

Pin the document rather than fetching it at build time if a reproducible build matters to you: download it, commit it, and update it deliberately. The info.version field changes whenever the contract does.

Importing into Postman or Insomnia

Both import from a URL directly:

File → Import → Link → https://theboatdb.com/docs/api/openapi.json

Then set the collection's bearer token to your API key once, rather than per request. Every endpoint inherits it.

What the document covers

Every partner-facing endpoint under https://api.theboatdb.com, with its parameters, response schemas, every error code and the headers we emit — including the rate-limit and caching headers, which are described alongside the responses that carry them.

Two things it deliberately omits: the dashboard's own key-management endpoints, which are authenticated by your signed-in session rather than an API key and are not part of the partner contract, and our inbound webhook endpoints, which authenticate by signature and are not callable by anyone else.