The REST API. Every endpoint.

Resource-oriented REST over HTTPS. JSON in, JSON out. An OpenAPI 3.1 spec you can point your own tooling at. Idempotency keys on every write. Cursor pagination on every list. No GraphQL gotchas, no RPC-flavored surprises.

OpenAPI 3.1 — generate a typed client in any language
143 endpoints across 8 resource families
Idempotency-Key header on writes · 24h retention
Cursor pagination · stable order · no skip/limit footguns

Download OpenAPI spec TypeScript SDK

Base URL

One host. Two versions.

The stable channel is what you want in production. The preview channel is how we ship breaking changes without breaking you.

Stable

https://api.boater.os/v1

Backwards-compatible. We never remove fields or change types. Additive only.

Preview · opt-in

https://api.boater.os/v2-preview

New shapes live here for 90 days before promotion. Pin with Boateros-Version.

Anatomy of a request

GET /v1/hulls/hull_YDV48219

Authorization header, an Accept header, optional API version pin. The response carries the resource, a request ID for support, and rate-limit headers.

terminal · curl

# Fetch a single hull by ID
curl https://api.boater.os/v1/hulls/hull_YDV48219 \
  -H "Authorization: Bearer $BOATEROS_KEY" \
  -H "Accept: application/json" \
  -H "Boateros-Version: 2026-04-01"

200 OK · application/json

{
  "id": "hull_YDV48219",
  "hin": "GRT40912B324",
  "make": "Grady-White",
  "model": "Freedom 307",
  "year": 2024,
  "length_ft": 31.17,
  "price_usd": 324900,
  "status": "available",
  "location_id": "loc_ftmyers",
  "created_at": "2026-03-22T14:12:04Z"
}

Error format

Nine HTTP codes. One envelope.

Every error returns the same shape: an HTTP status, a machine-readable code, a human message, and a request_id for when you need to talk to us.

400 bad_request Malformed JSON, missing required field, or invalid parameter shape.

401 unauthenticated Missing or invalid API key. Check the Authorization header.

403 forbidden Key is valid but lacks the scope required for this resource.

404 not_found Resource does not exist or the dealership context cannot see it.

409 conflict State collision — usually a concurrent write on the same resource.

422 unprocessable Validation failed. See error.details[] for field-level messages.

429 rate_limited Too many requests. Respect Retry-After and back off exponentially.

500 server_error Something broke on our side. Safe to retry with the same idempotency key.

503 unavailable Maintenance window or regional failover. Retry in 30–60 seconds.

Pagination

Cursor-based. Always.

List endpoints accept limit, starting_after, and ending_before. The response returns has_more and the next cursor. No offset math, no duplicate rows on insert, no skipped rows on delete.

GET /v1/hulls?limit=50&starting_after=hull_YDV48219

{
  "data": [ /* up to 50 hulls */ ],
  "has_more": true,
  "next_cursor": "hull_ZXK20441",
  "prev_cursor": "hull_YDV48219"
}

Idempotency

Safe retries, always.

Every POST, PUT, and PATCH accepts an Idempotency-Key header. Send the same UUID on retry, get the same response back. Kept for 24 hours.

POST /v1/deals · idempotent

curl -X POST https://api.boater.os/v1/deals \
  -H "Authorization: Bearer $BOATEROS_KEY" \
  -H "Idempotency-Key: 7c4f1a0e-2d8b-4c3a-9f12-ab12e34d5f67" \
  -H "Content-Type: application/json" \
  -d '{"hull_id":"hull_YDV48219","buyer_id":"con_4412","offer_usd":298000}'