Competition Tools API¶

This page covers the merging and splitting tools for events within a competition. These let you restructure your event programme programmatically — for example, splitting a large field event into two pools, or combining two poorly-attended events into one.

Both tools operate on an existing event and are addressed through the competition's natural key URL pattern:

/api/x/{year}/{country}/{slug}/event/{event_id}/split-events/
/api/x/{year}/{country}/{slug}/event/{event_id}/merge-events/

The {event_id} is the competition-specific event identifier string (e.g. T01, F1), not the database primary key.

Example URLs use the test server

The example URLs in this section deliberately point at the test server (test-data.opentrack.run) so you can experiment with write operations without risking live data. Use the live server domain or federation domain when you are ready to make real changes.

Endpoint Summary¶

Endpoint	Method	Purpose
`/api/x/{year}/{country}/{slug}/event/{event_id}/split-events/`	`POST`	Split one event into two or more child events (e.g. by age group or gender)
`/api/x/{year}/{country}/{slug}/event/{event_id}/merge-events/`	`POST`	Merge two or more events into a single target event

Both endpoints:

require authentication (Authorization: Token ... header) — they are intended for the competition's directors/admins
are asynchronous: they queue a background task and return immediately with a confirmation message
send an email notification when the background task completes
are available only within 7 days of the competition finish date (the standard write-window for competitions)
cannot be used on events that already have results — make sure you run these tools before any results are entered

Allow time for the process to complete

Splitting and merging run as background tasks, so how long they take depends on how busy the servers are. Allow up to 10 minutes for the process to complete. If you have not received the completion email after 20 minutes, it is worth emailing us at support@opentrack.run.

Splitting Events¶

Use this to split a single event into multiple child events. A typical use case is a field event with too many entries to run as one pool: split it into ...A and ...B pools, each covering different age groups.

Endpoint¶

POST /api/x/{year}/{country}/{slug}/event/{event_id}/split-events/

Request Body¶

Form-encoded (or JSON) with a single events field: a JSON-encoded list of rows, where each row is:

Position	Field	Example	Notes
0	`suffix`	`A`	Single letter `A`–`Z`; appended to the parent event id to form the child id (e.g. `T01` → `T01A`)
1	`genders`	`M`	`M`, `F` or `MF`
2	`age_groups`	`V35,V40`	Comma-separated list of age groups assigned to this child

Each suffix must be unique within the request, and the age groups must be valid for the competition.

Constraints¶

The competition's entries must be closed before events can be split
The event being split must not already have results
Every age group currently entered in the parent event must be assigned to one of the child events — the request is rejected if any competitors would be left behind

Example¶

Split the event T01 into two children — T01A for V35/V40 men and T01B for V45/V50 men:

TOKEN=$(curl -s -X POST "https://test-data.opentrack.run/api/get-auth-token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'username=api-test@mailinator.com&password=apitest' | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

curl -X POST "https://test-data.opentrack.run/api/x/2026/GBR/lac-open-2/event/T01/split-events/" \
  -H "Authorization: Token $TOKEN" \
  -d 'events=[["A","M","V35,V40"],["B","M","V45,V50"]]'

Response¶

On success the endpoint returns 200 with a confirmation message. The actual work happens in the background, and an email notification is sent to you once the split completes:

{
  "message": "Successfully scheduled background tasks for splitting events. Please wait up to 5 minutes. You will receive an email notification once the process is complete."
}

Web Interface¶

Prefer doing this by hand? Both splitting and merging are available on the event's Advanced Configuration page in the web interface — see Merge Events in the competition management manual.

What Happens¶

Child events are created with ids formed from the parent id + suffix (e.g. T01A, T01B)
Competitors and entries are moved to the child event matching their age group/gender
The parent event is deleted once all child events have been created and populated — so make sure you split out all age groups and genders from the parent; there is nothing left behind afterwards

No changes while the split is running

Do not make any changes to the competition's events while the split process is under way — the web interface blocks event edits until the background task finishes, and you should follow the same rule when working through the API. Wait for the completion email before making further changes.

A backup is created automatically

Before the split starts, a backup of the whole competition is created at:

/x/{year}/{country}/{slug}-backup/

(note the -backup suffix on the slug). It is deleted automatically on successful completion; if it is still present, something went wrong and you can use it to inspect or restore the competition.

Merging Events¶

Use this to combine two or more events into a single target event. A typical use case is two events with very few entries (e.g. M65 800m and M70 800m) that are better run together.

Endpoint¶

POST /api/x/{year}/{country}/{slug}/event/{event_id}/merge-events/

Request Body¶

Field	Type	Required	Description
`events_to_merge`	List of strings	Yes	Event ids to merge into the target event (the event in the URL)
`age`	String	No	New age group(s) for the merged event, e.g. `V35, V40` or `ALL`
`gender`	String	No	New gender(s) for the merged event, e.g. `M`, `F`, `MF`
`category`	String	No	New category for the merged event
`name`	String	No	New event name
`test`	Boolean	No	If `true`, run as a test without making changes
`new_event_id`	String	No	Optional new id for the merged event

Example¶

Merge events T01 and T02 into the target event T00, renaming the result:

TOKEN=$(curl -s -X POST "https://test-data.opentrack.run/api/get-auth-token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'username=api-test@mailinator.com&password=apitest' | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

curl -X POST "https://test-data.opentrack.run/api/x/2026/GBR/lac-open-2/event/T00/merge-events/" \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events_to_merge": ["T01", "T02"],
    "age": "V35, V40, V45, V50",
    "gender": "M",
    "name": "800m Men Masters"
  }'

Response¶

On success the endpoint returns 200 with a confirmation message. The actual work happens in the background, and an email notification is sent to you once the merge completes:

{
  "message": "Successfully queued merging events (['T01', 'T02'] -> T00). Please wait for the background task to complete. You will receive an email notification once the process is complete."
}

Web Interface¶

Prefer doing this by hand? Both merging and splitting are available on the event's Advanced Configuration page in the web interface — see Merge Events in the competition management manual.

Constraints¶

The competition's entries must be closed before events can be merged
None of the events involved (target or sources) may already have results — the request is rejected if any do
The target event and every source event must exist

Notes¶

The test flag is available on merge only — it runs the merge in test mode without changing anything, so you can validate your request first. Splitting has no equivalent; it always runs for real, so double-check your split rows before submitting
Both tools are best used before results are entered — the web interface blocks splitting/merging once results exist, and the merge endpoint rejects the request if any event has results
For the web-interface equivalents, see Merging Events in the competition management manual