Contest

The Contest resource manages contest sessions — the Contesting module's grouping of QSOs into a contest run — and the links between a session and its QSOs. It is the API counterpart to the Contesting pages in the web UI and lets external tools (loggers, offline mirrors, sync clients) read and replicate contest sessions instead of rebuilding them by hand via Import Historical Contests.

• Base path: /api/v2/contest
• Scopes: contest:read, contest:write, contest:delete
• Since version: dev, not released yet

Endpoints

A session belonging to another user returns 404 not_found, never 403 — the API never confirms that a foreign id exists.

The session object

{
  "id": 17,
  "contest": "DARC-WAG",
  "contest_name": "Worked All Germany Contest",
  "time_start": "2026-10-17 15:00:00",
  "time_end": "2026-10-18 15:00:00",
  "station_id": 3,
  "comment": "SO ABHP",
  "settings": {
    "exchangetype": "Serialexchange",
    "copyexchangeto": "dok",
    "exchangefields": ["serial", "exchange"],
    "callbook_lookup": true,
    "custom_name": "",
    "serial_per_band": false,
    "serial_scope": "station"
  },
  "qso_count": 412,
  "created_at": "2026-10-17 14:52:11",
  "updated_at": "2026-10-18 15:04:37"
}

The contest name

One and the same value goes by three different names, which is easy to trip over:

So a contest an administrator created with ADIF Name = DARC-WAG is addressed as "contest": "DARC-WAG" here, and every QSO exported from such a session carries <CONTEST_ID:8>DARC-WAG.

Session settings

settings is a JSON object. On read it is always returned complete, merged over the module defaults, so a client never has to know which keys were stored. On write only the keys you send are validated and merged over the existing values.

exchangefields is an array and therefore the one place where the API's usual scalar-only body rule does not apply — settings, qso_ids, link_qso_ids and unlink_qso_ids may be nested, every other field must stay scalar.

exchangetype is a derived legacy field. Whatever you send is ignored and recomputed from exchangefields, exactly as the web UI does it, so the two can never drift apart:

An unknown settings key or an invalid value returns 400 validation_error with the individual messages in error.details.errors.

List sessions

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

Sessions are returned newest first (by time_start, then id). The list is not paginated and carries no qso_ids — fetch a single session for that.

A station_id the token does not own is rejected with 403 forbidden rather than silently dropped.

Fetch a single session

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

The response is the session object plus qso_ids, the sorted list of linked QSO primary keys — the same ids the QSO resource uses, so a client can mirror the linkage:

{
  "data": {
    "id": 17,
    "contest": "DARC-WAG",
    "qso_count": 3,
    "qso_ids": [48190, 48200, 48215]
  }
}

Create a session

curl -X POST "https://<WAVELOG_URL>/index.php/api/v2/contest" \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{
           "contest": "DARC-WAG",
           "time_start": "2026-10-17 15:00",
           "time_end": "2026-10-18 15:00",
           "station_id": 3,
           "comment": "SO ABHP",
           "settings": {
             "exchangefields": ["serial", "exchange"],
             "copyexchangeto": "dok"
           }
         }'

On success the answer is 201 Created with a Location header pointing at the new session and the created session in data.

The contest must exist and be active in the contest catalog; an unknown or deactivated contest returns 400 validation_error. The Catalog resource lists the accepted values. The qso_ids list is validated before the session is created, so a rejected link list can never leave a stale empty session behind.

Update a session

curl -X PATCH "https://<WAVELOG_URL>/index.php/api/v2/contest/17" \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{"time_end": "2026-10-18 16:00", "settings": {"serial_per_band": true}}'

Only the fields present in the body change. settings is merged key by key over the stored settings — sending {"serial_per_band": true} leaves every other setting untouched. A body with no editable field and no link list returns 400 validation_error.

Linking and unlinking QSOs

The URL space has no sub-paths, so the linkage travels in the body of a PATCH:

curl -X PATCH "https://<WAVELOG_URL>/index.php/api/v2/contest/17" \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{"link_qso_ids": [48190, 48200], "unlink_qso_ids": [47001]}'

The response is the session object with the outcome appended — the extra fields only appear when the request actually contained a link list:

{
  "data": {
    "id": 17,
    "qso_count": 413,
    "linked": 2,
    "skipped": [],
    "unlinked": 1
  }
}

Linking is idempotent: an id already linked to this session is a silent no-op, so a sync client can re-send its full list without special-casing. An id linked to another session is never stolen — it lands in skipped.

Linking also sets the QSO's CONTEST_ID field to the session's contest, and unlinking clears it again (only on QSOs that were really linked to this session), mirroring the attach/detach workflow of the advanced logbook.

QSO ids that do not belong to the token owner return 403 forbidden with the offending ids in error.details.qso_ids; the whole list is validated before anything is applied, so a rejected request changes nothing.

Delete a session

curl -X DELETE "https://<WAVELOG_URL>/index.php/api/v2/contest/17" \
     -H "Authorization: Bearer wl2_your_token_here"

Returns 204 No Content. By default the linked QSOs stay in the logbook and only lose their session link — the same as unchecking the box in the web UI.

To tear the whole run down, including the QSOs:

curl -X DELETE "https://<WAVELOG_URL>/index.php/api/v2/contest/17?delete_qsos=true" \
     -H "Authorization: Bearer wl2_your_token_here"

Clubstation tokens

For a clubstation token the member's permission level applies on top of the scopes, matching what the web UI allows:

A member below officer level that tries to edit the session itself gets 403 insufficient_club_permission. Sessions are shared club infrastructure, so their fields stay officer-only, while attaching one's own QSOs to a running session does not — the same split the advanced logbook uses.

Errors