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
-
Download the TopHeats API v1 collection. In Postman, click Import and select the downloaded JSON file.

-
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/v1for this English guide. Usehttps://topheats.ru/api/v1for the Russian site.event_id— the event ID from its page URL. For example,/events/272contains the ID272.sport_id— your sport's ID fromGET {{base_url}}/sports?locale=en. Fill this in after sending List sports in step 4.
-
Click Vault and open Local Vault. On first use, Postman will ask you to set it up. Enter
topheats-api-keyin Key and your API key in Value. In Allowed domains, enter the hostname frombase_url:topheats.comortopheats.ru.

-
Open List sports and click Send. When you receive
200 OK, find your sport in thedataarray. Copy itsidintosport_idon the Variables tab.
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
pageusingdata.page,data.limit, anddata.total, as with events. The example has four divisions, two per page. Keepresult_page=1when moving to the next page of divisions. The maximum is 20 divisions per page. - Athletes. Each division has its own pagination in
results. Ifresults.page × results.limit < results.total, request the nextresult_pagewith that division'sdivision_idandpage=1. Keep the sameresult_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.
- 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, andathlete.id. Store IDs as strings. - If data changes while you are reading pages, repeat the comparison. Pages are read at different times.
- 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.