API Reference

This reference covers the buoy endpoints.

Base URL

All endpoints are served from:

https://api.thebuoy.app/v2

Methods

All endpoints are GET.

Authentication

All endpoints except GET /buoys/search and GET /buoys/nearest require a Bearer token:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Response format

Every response uses a consistent envelope:

{
  "status": "success",
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-27T09:00:00Z",
    "page": 1,
    "per_page": 50,
    "total_pages": 4
  }
}

Error responses:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Error codes

HTTP status	`error` value	Meaning
`400`	`bad_request`	Missing or malformed parameters
`401`	`unauthorized`	Invalid or missing API key
`404`	`resource_not_found`	Resource doesn’t exist
`422`	`validation_failed`	Parameter validation error
`429`	`rate_limit_exceeded`	Hourly quota exceeded

Pagination

List endpoints accept page and per_page parameters. Pagination metadata is always in meta:

"meta": {
  "page": 2,
  "per_page": 50,
  "total_pages": 10,
  "timestamp": "2026-03-27T09:00:00Z"
}

Units

Measurement	Unit
Wave height	metres (m)
Wave period	seconds (s)
Wave direction	degrees (°), clockwise from north
Wind speed	km/h
Temperature	°C
Distance (radius)	kilometres (km)

Overview

Endpoints

Base URL

Methods

Authentication

Response format

Error codes

Units

​Base URL

​Methods

​Authentication

​Response format

​Error codes

​Pagination

​Units

Base URL

Methods

Authentication

Response format

Error codes

Pagination

Units