Integrations

How to connect to TopHeats API v1

Connect to TopHeats API v1, retrieve published events and final results, and keep the data on your website up to date.

7 min read Updated: 14.11.2026

Use TopHeats API to display published events and saved final results on your website. Send GET requests over HTTPS from your server. Responses use JSON.

Get an API key

Ask your TopHeats administrator for a key. Specify the sports and events you need. This integration requires the sports, events, and results scopes. The administrator sets the permissions, request limit, and expiry date.

The key is shown once when it is created. Store it on your server, for example in the TOPHEATS_API_KEY environment variable. Keep it out of URLs, browser JavaScript, repositories, and logs. Include Authorization: Bearer <key> in every request.

Send your first request in Postman

  1. Download the TopHeats API v1 collection. In Postman, click Import and select the downloaded JSON file.

    Import button in Postman

  2. Select the TopHeats API v1 collection in the sidebar and open Variables. Enter your values in the Value column.

    • base_url — https://topheats.com/api/v1 for this English guide. Use https://topheats.ru/api/v1 for the Russian site.
    • event_id — the event ID from its page URL. For example, /events/272 contains the ID 272.
    • sport_id — your sport's ID from GET {{base_url}}/sports?locale=en. Fill this in after sending List sports in step 4.
  3. Click Vault and open Local Vault. On first use, Postman will ask you to set it up. Enter topheats-api-key in Key and your API key in Value. In Allowed domains, enter the hostname from base_url: topheats.com or topheats.ru.

    Vault button in Postman

    Key, Value, and Allowed domains in Local Vault before entering the domain

  4. Open List sports and click Send. When you receive 200 OK, find your sport in the data array. Copy its id into sport_id on the Variables tab.

    Send button in Postman

If you select an event using List events, copy its id from data.items into event_id. To filter by date, enable from and to on the Params tab and enter your date range.

Load events and results

The examples use TSK Surf Series no.4 '26 on a local test instance. To reproduce them, ask for a key for that instance with the sports, events, and results scopes, sport 10, and access to event 272 only.

In Postman, set base_url to http://localhost:3000/api/v1, sport_id to 10, and event_id to 272. Use the local instance's key for the topheats-api-key secret and set Allowed domains to localhost. In List events, enable the collection's preset from and to parameters for 17 October 2026.

1. Get the sports

Before running the example, set the local instance's key in the TOPHEATS_API_KEY environment variable.

TOPHEATS_API_URL='http://localhost:3000/api/v1'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/sports?locale=en"

2. List events

Use the sport's id from /sports. This example uses 10 (Surfing). The from and to parameters set inclusive bounds for the event start date. Here they cover 17 October 2026 in UTC. The locale=en parameter requests English names.

SPORT_ID='10'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events?sport_id=$SPORT_ID&from=2026-10-17T00:00:00Z&to=2026-10-17T23:59:59.999Z&locale=en&page=1&limit=20"

Read events from data.items. Start with page=1 and increase page while data.page × data.limit < data.total. Keep the same filters and page size. The limit range is 1–100.

3. Get event details

Use the event's id from data.items. This example uses 272.

EVENT_ID='272'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID?locale=en"

The response contains event details and up to 1,000 divisions in data.divisions. Use /results to load the full results.

4. Get final results

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID/results?locale=en&page=1&limit=2&result_page=1&result_limit=1"
  • Divisions. Iterate through page using data.page, data.limit, and data.total, as with events. The example has four divisions, two per page. Keep result_page=1 when moving to the next page of divisions. The maximum is 20 divisions per page.
  • Athletes. Each division has its own pagination in results. If results.page × results.limit < results.total, request the next result_page with that division's division_id and page=1. Keep the same result_limit, up to 100 athletes per page. Repeat until you have read all athletes in that division.

On the second page of divisions, find Men's Open, ID 803. The following request returns the second page of athletes in this division. With result_limit=1, it contains one row.

DIVISION_ID='803'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID/results?locale=en&division_id=$DIVISION_ID&page=1&limit=2&result_page=2&result_limit=1"

Read a result

The API returns saved final results with place and rank. In this example, result.value contains a performance score of 11.06, and rating_points contains 800 ranking points.

The following sample response is based on the saved results. Athlete details are anonymized. The generated_at and request_id values are illustrative.

{
  "data": {
    "event_id": "272",
    "items": [
      {
        "id": "803",
        "name": "Men's Open",
        "gender": "male",
        "age_from": null,
        "age_to": null,
        "discipline": {"id": "101", "name": "Shortboard"},
        "scoring": {"max_score": null, "lower_is_better": false, "result_mode": "advancement"},
        "results": {
          "items": [
            {"athlete": {"id": "athlete_2", "name": "Athlete", "avatar_url": null, "profile_url": null}, "place": 2, "rank": 2, "rating_points": 800, "result": {"value": 11.06, "unit": "points", "display": "11.06", "status": "recorded"}}
          ],
          "total": 13,
          "page": 2,
          "limit": 1
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 2
  },
  "generated_at": "2026-11-05T21:54:51.061Z",
  "request_id": "0123456789abcdef01234567"
}

Use result.display to show a result on your website. In result.unit, points means points, seconds means seconds, and count means repetitions. A recorded score of zero returns "value": 0, "display": "0", and "status": "recorded". If there is no result, value and display are null, and the status is no_result.

Set up regular updates

Each response includes generated_at, the time it was generated. Schedule updates on your server and read every page of the required selection on each run.

  1. Collect fresh data separately from your current copy. Match events by id, divisions by event and division ID, and result rows by event ID, division ID, and athlete.id. Store IDs as strings.
  2. If data changes while you are reading pages, repeat the comparison. Pages are read at different times.
  3. After a successful full run, update your copy and remove events, divisions, and results that are no longer returned by the same selection. If a request fails, keep your current copy and finish the comparison after access is restored.

Troubleshoot errors

The request limit applies per key across all routes within each UTC calendar minute. For 429, the Retry-After header gives the number of seconds until the next minute. For a temporarily blocked key (403), it gives the number of seconds until the key is unblocked.

HTTP / error.code What to check
400 / invalid_parameter Check parameter names, values, and formats. Send each parameter only once.
401 / invalid_api_key Check the Authorization header, the key value, expiry, and whether the key has been revoked.
403 / scope_forbidden, sport_forbidden, api_key_blocked Check the key's route and sport permissions. For a temporary block, wait Retry-After seconds.
404 / endpoint_not_found, event_not_found, division_not_found Check the path and IDs. The event may be inaccessible to this key.
405 / method_not_allowed Use GET.
429 / rate_limit_exceeded Wait Retry-After seconds, then retry.
500 / internal_error Retry later. If the error persists, give the request_id to your TopHeats administrator.

The request_id helps locate a specific request during troubleshooting. Include it with the HTTP status and error code when asking for help.

Didn't find an answer?

Write to us. We will help and add your question to the docs.

Contact support