Skip to content

Setting up and manipulating competitions

These pages are aimed at meeting directors who want to programmatically "do things" to an existing competition.

The user you authenticate as should have Meeting Director rights, which can be seen on the Manage | Officials page for the competition. These rights can be granted per competition, or per organiser.

Common tasks

If you've taken your entries, and then planned a meeting in a spreadsheet, you may want to manipulate the heat structure and the precise timetable.

You may also want to create competitors in bulk and assign them to events, or update info about their participation.

Database Concepts

We use Amazon's version of MongoDB to store data within a competition. This is NOT a classic relational database. Documents may have varying fields. In general, you'll call an API to get back a JSON version of the document you want; then, in some cases, manipulate the data and POST or PUT this back to the server. The main record types are:

  • Competition - one top level record with many settings, often corresponding to the Manage pages.
  • Events - many EventSpec records, one per item in the competition's Events grid
  • Units - a unit corresponds to a heat in a race, or a throwing pool. There are different unit classes with different structures for running races, horizontal jumps, throws, high jump/pole vault, and relays.
  • Competitors - one human in the competition. This contains nested data for the events they entered - so if you're running 800 and 1500, events_entered will be a list of two structures, each defining PB/SB, maybe time checked in and other things

Referencing a competition

To manipulate a competition you need to reference it. The easiest way is the natural key URL pattern, based on the competition's year, country and slug — you can read these straight from the competition's public URL:

/api/x/{year}/{country}/{slug}/

For example: https://test-data.opentrack.run/api/x/2026/GBR/lac-open-2/

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.

Events, units and competitors are then nested under this:

/api/x/{year}/{country}/{slug}/event/
/api/x/{year}/{country}/{slug}/event/{event_id}/
/api/x/{year}/{country}/{slug}/event/{event_id}/rounds/
/api/x/{year}/{country}/{slug}/competitors/

This is the recommended way to work with a specific competition: you don't need to look up any database IDs.

The older approach is to use the competition's UUID (the id field, common to both the SQL and Mongo Competition records). These can be obtained from the API to list or find a competition, or by browsing to the competition and appending json/ to the URL and looking for the id property.

Once you have a way to reference the competition, you can work with the events, competitors or units.