Skip to main content

​
Base URL

All endpoints are served from: 
https://thesurfkit.com/api/v2

​
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 statuserror valueMeaning
400bad_requestMissing or malformed parameters
401unauthorizedInvalid or missing API key
404resource_not_foundResource doesn’t exist
422validation_failedParameter validation error
429rate_limit_exceededHourly 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

MeasurementUnit
Wave heightmetres (m)
Wave periodseconds (s)
Wave directiondegrees (°), clockwise from north
Wind speedkm/h
Temperature°C
Distance (radius)kilometres (km)