> ## 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.

# API Reference

> Buoy endpoints — list, search, readings, and charts.

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:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/authentication) for details.

## Response format

Every response uses a consistent envelope:

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

Error responses:

```json theme={null}
{
  "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`:

```json theme={null}
"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)                   |