Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thebuoy.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Getting an API Key

API access is currently by invitation. To request credentials, email thomas@thebuoy.app. Once your request is approved, you’ll receive an API key. Store it securely — it’s shown only once and cannot be retrieved later. If you lose it, we can generate a new one, which immediately invalidates the old one.
If your key is compromised, contact support to rotate it.

​
Using Your API Key

Include your API key in every request using the Authorization header: 
Authorization: Bearer YOUR_API_KEY

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys?country=FR"

​
Query parameter (alternative)

If you can’t set headers, pass the key as a query parameter: 
curl "https://api.thebuoy.app/v2/buoys?country=FR&api_key=YOUR_API_KEY"
Prefer the Authorization header — query parameters appear in server logs and browser history.

​
Public Endpoints

Two endpoints do not require authentication and are available to anyone:
EndpointDescription
GET /api/v2/buoys/searchSearch buoys by name or identifier
GET /api/v2/buoys/nearestFind the nearest buoy to coordinates

​
Authentication Errors

​
401 Unauthorized — missing key
{
  "error": "unauthorized",
  "message": "API key required"
}
​
401 Unauthorized — invalid key
{
  "error": "unauthorized",
  "message": "Invalid API key"
}

​
Rate Limit Headers

Every authenticated response includes these headers so you can track your usage: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1735326000
HeaderDescription
X-RateLimit-LimitYour hourly request quota
X-RateLimit-RemainingRequests remaining this hour
X-RateLimit-ResetUnix timestamp when the quota resets
When your quota is exceeded, the API returns 429 Too Many Requests: 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded 1000 requests per hour",
  "retry_after": 1847,
  "reset_at": "2026-03-27T15:00:00Z"
}
See the Rate Limits guide for details on planning around quotas.