API v2

Wavelog's REST API v2 is a modern, resource-oriented HTTP API for third-party tools — radios, external loggers, monitoring systems and your own scripts. It runs side by side with the legacy v1 API: v2 does not replace v1, and both can be used at the same time.

What's different from v1

Base URL

Every endpoint lives under the api/v2 prefix:

https://<your-wavelog-host>/index.php/api/v2/<resource>[/<id>]

• <resource> is a singular, lowercase name (qso, station, radio, statistic, confirmation, lookup, club, token).
• <id> is the numeric primary key of a single item, where applicable.

That is the complete URL space: a path with more than those two segments is not a URL that exists and returns 404 not_found, rather than being answered by ignoring the surplus. A trailing slash is fine.

/api/v2/qso          ✅ list
/api/v2/qso/42       ✅ single item
/api/v2/qso/         ✅ same as /api/v2/qso
/api/v2/qso/42/notes ❌ 404 not_found

Depending on your webserver configuration you may be able to omit the index.php/ segment. All examples in this documentation include it for maximum compatibility.

Available resources

Authentication

Creating a token

1. Log in to Wavelog and open the API section from the user menu.
2. Create a new API v2 token. You choose:
   • a name (to recognise the token later),
   • one or more scopes (see Scopes),
   • an expiry: 30, 90 or 365 days, or never.
3. The full token (wl2_…) is shown exactly once, right after creation. Copy it immediately — Wavelog only stores a hash and can never show it again.

You can revoke a token at any time from the same screen; revocation is immediate.

Sending the token

Send the token in the Authorization header using the Bearer scheme:

Authorization: Bearer wl2_your_token_here

As a fallback, an X-API-Key header is also accepted:

X-API-Key: wl2_your_token_here

Scopes

Permissions are granular and follow the pattern <resource>:<action>:

Scopes are independent, so you can mint a read-only token, a write-only token, or any combination. A request whose verb needs a scope the token does not carry is rejected with 403 insufficient_scope.

The full set of scopes offered when creating a token is:

The Token resource (whoami) needs no scope — any valid token may read its own metadata.

Scopes are the only permission layer for a personal token. A clubstation token passes a second one on top: the member's permission level on the club. Holding station:write does not help if the level behind the token is below officer.

Request and response conventions

HTTP verbs

Not every resource implements every verb (for example, Radio has no PATCH, and Statistic is read-only). An unsupported verb returns 405 method_not_allowed together with an Allow header listing exactly the verbs that resource does implement:

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST, PATCH, DELETE

The verb is checked before the scope, so a POST to a read-only resource is a 405 and not a 403: the scope it would need (lookup:write) does not exist and no token can ever hold it, so reporting a missing scope would point at the wrong problem.

Request bodies

• Send write payloads as JSON with Content-Type: application/json.
• Body fields must be scalar values (string, number, boolean or null). Nested objects or arrays are rejected with 400 validation_error.
• Malformed JSON returns 400 invalid_json.

Success responses

Successful responses use a slim envelope. The payload is always under data. Every JSON success response also includes a meta block with common request context:

Resource-specific metadata (pagination, lookup detail, statistic profile, ...) is added to the same meta object.

Examples:

{
  "data": { "id": 42, "call": "N9EAT" },
  "meta": {
    "timestamp": "2026-07-18T12:34:56+00:00",
    "resource": "qso",
    "method": "GET"
  }
}

{
  "data": [ { "id": 42 }, { "id": 43 } ],
  "meta": {
    "timestamp": "2026-07-18T12:34:56+00:00",
    "resource": "qso",
    "method": "GET",
    "page": 1,
    "per_page": 50,
    "count": 2
  }
}

A successful DELETE returns 204 No Content with an empty body.

Error responses

Errors use an error envelope and a matching HTTP status code:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing the required scope: qso:write",
    "details": { "required_scope": "qso:write" }
  }
}

Pagination

List endpoints that can return many rows (currently QSO) support pagination through query parameters:

The pagination fields are part of meta and report the page state:

{
  "data": [ { "id": 42 } ],
  "meta": {
    "timestamp": "2026-07-18T12:34:56+00:00",
    "resource": "qso",
    "method": "GET",
    "page": 1,
    "per_page": 50,
    "count": 50,
    "total": 237,
    "total_pages": 5,
    "has_more": true
  }
}

To iterate the full set, request pages until has_more is false (equivalently, until page reaches total_pages). You never need to probe for an empty page.

Rate limiting

Rate limiting is opt-in: it is inactive until the instance owner configures it, and it uses a sliding window. When a limit is exceeded, the API returns 429 rate_limited with details.retry_after (seconds to wait). If no limit is configured, no throttling is applied — but please still call the API only when you actually have new data to send or fetch.

Buckets

Every v2 request passes through up to two independent counters:

A client with a valid token passes through both. A client with an invalid token never gets past the first — which is the point: a rejected token never reaches the per-token bucket, so without api_v2_auth the token keyspace could be probed at full speed.

api_v2_auth is deliberately not per resource. If it were, the limit could be sidestepped by rotating the resource in the URL (/qso, /station, /radio, …).

Configuration

Limits live in application/config/config.php (Docker installations: application/config/docker/config.php). Each entry sets a maximum number of requests within a window in seconds:

$config['api_rate_limits'] = [
    // API v2 — bucket names carry the "api_v2_" prefix
    'api_v2_auth'      => ['requests' => 10,  'window' => 120],
    'api_v2_qso'       => ['requests' => 120, 'window' => 60],
    'api_v2_lookup'    => ['requests' => 60,  'window' => 60],
    'api_v2_statistic' => ['requests' => 30,  'window' => 60],

    // v1 endpoints keep their bare method names
    'private_lookup'   => ['requests' => 60,  'window' => 60],

    // applies to every bucket not listed above
    'default'          => ['requests' => 60,  'window' => 60],
];

v1 and v2 share the same config array but never collide: v1 buckets are named after the API method (lookup, private_lookup, qso), v2 buckets always carry the api_v2_ prefix. Both are configured independently.

To disable rate limiting entirely, set $config['api_rate_limits'] = null; or leave it commented out.

Withheld user data

Endpoints that describe other people's accounts disclose personal data, and what an instance may hand out differs per country. The instance owner therefore picks which of those fields to withhold:

$config['apiv2_hide_userdata'] = ['user_email', 'user_locator'];

The listed fields are left out of the response entirely — they are not blanked, not null, the key is simply absent. An empty array (the default) discloses everything.

Currently this affects the Club resource, the only one that returns another user's account data.

Fields which are always returned and cannot be withheld are:

user_id
user_callsign
permission_level

Fields which can be withheld are:

user_firstname
user_lastname
user_locator
user_name
user_email
user_language

CORS

The API answers OPTIONS preflight requests with 204 No Content and permits cross-origin calls (Access-Control-Allow-Origin: *) for the GET, POST, PATCH, DELETE and OPTIONS methods, allowing the Authorization, Content-Type and X-API-Key headers.

Status endpoint

GET /api/v2 (and GET /api/v2/status) is public — no token required — and is handy for a quick reachability check:

curl https://<WAVELOG_URL>/index.php/api/v2/status

{
  "data": { "name": "Wavelog API", "status": "ok" },
  "meta": {
    "timestamp": "2026-07-18T12:34:56+00:00",
    "resource": "status",
    "method": "GET"
  }
}

Quickstart

List your station locations:

curl https://<WAVELOG_URL>/index.php/api/v2/station \
     -H "Authorization: Bearer wl2_your_token_here"

Create a QSO on station location 1:

curl -X POST https://<WAVELOG_URL>/index.php/api/v2/qso \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{
           "station_profile_id": 1,
           "call": "N9EAT",
           "band": "20m",
           "mode": "SSB",
           "freq": 14075000,
           "qso_date": "2026-06-16",
           "time_on": "1706",
           "rst_sent": "59",
           "rst_rcvd": "57"
         }'

See the per-resource pages for the full field reference: QSO · Station · Radio · Statistic · Lookup · Club · Token.

If your token belongs to a clubstation rather than to your own account, read Clubstations as well — the permission level changes what several of these resources return.