Public results API (v1)
Third-party organizers push the results of a section and anyone reads the published ones. The API lives under /api/v1.
Authentication
An owner or admin of the organization makes a key in the organizer console. The key is shown once and stored hashed; revoking it stops it at once. Send it on every push in the X-Api-Key header.
X-Api-Key: tcsa_AbCdEfGh_0123456789abcdefghijklmnopqrstuvwx
The same key is accepted as a bearer token:
Authorization: Bearer tcsa_AbCdEfGh_0123456789abcdefghijklmnopqrstuvwxPushing results
A push names one section of an event of the key's organization. The section must be one that shows a TRF file (not one paired here). A push replaces what the section shows, as a file confirmed in the console does.
TRF file
The request body is the TRF file itself. A file the importer refuses answers 422 and stores nothing; the problems array names the reason with no player data.
POST /api/v1/organizer/sections/{sectionId}/trf
Content-Type: text/plain
Content-Disposition: attachment; filename=open-naco-round5.trf
<the TRF file's bytes>
Standings JSON
The JSON carries the standings only: players with their starting rank, name, points and rank, and the optional FIDE facts. It replaces the section's standings; it carries no pairings. Names are at most 33 characters, FIDE IDs at most 11 digits, points at most 100.
POST /api/v1/organizer/sections/{sectionId}/standings
Content-Type: application/json
{
"tournamentName": "Open Naco 2026",
"players": [
{
"startRank": 1,
"name": "Perez, Juan",
"fideId": "6400000",
"title": "GM",
"rating": 2450,
"federation": "DOM",
"points": 7.5,
"rank": 1
}
]
}
A refused JSON answers 422 with problems: json, players, startRank, name, fideId, title, federation, rating, points or rank.
Limits and idempotency
One key makes at most 60 requests per minute; the next ones answer 429 with Retry-After (and X-RateLimit-Limit and X-RateLimit-Remaining on every authenticated answer). A TRF file is at most 2 MiB and a standings JSON at most 1 MiB.
Pushing the same file or the same standings again answers unchanged and changes nothing. Every authenticated push writes an audit row, a refused one included; a request without a working key writes none, and a rejected push stores no result.
Statuses
The body of every answer names its status in the status field.
| Status | Meaning |
|---|---|
200 accepted | The results were stored; the section shows them, marked unofficial until an owner or admin confirms them. |
200 unchanged | The section already shows exactly this push; nothing changed. |
401 | The key is missing, not ours or revoked. |
403 notAllowed | The scope may not push for this section. An API key always may, so this is a guard: a section of another organization, or an unknown one, answers 404. |
409 native | The section is paired here: it takes no file and no standings. |
413 | The push is larger than the limit; nothing was stored. |
415 | The standings endpoint expects Content-Type: application/json. |
422 invalid | The file or the JSON is not valid; nothing was stored. |
429 | The key went over its minute; wait Retry-After seconds. |
404 notFound | The key's organization has no such section. |
Unofficial results
Results pushed through the API are marked unofficial on the public pages. An owner or admin of the organization confirms them in the section's file history, and the marker goes away.
Reading published results
No key is needed. The events are the published ones, newest first, 20 per page (?page=N); a draft, a page our staff removed and any personal data are never returned. Every endpoint is under the /api/v1 version prefix.
GET /api/v1/public/events?page=1
GET /api/v1/public/events/{eventId}
GET /api/v1/public/events/{eventId}/sections/{sectionId}/standings
{
"page": 1,
"pages": 3,
"total": 41,
"events": [
{ "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" }
]
}
One published event by id, with its sections; a draft, a removed page or an unknown id is 404.
{
"event": { "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" },
"sections": [
{ "id": "…", "slug": "open", "name": "Open", "source": "trf" }
]
}
The section's standings carry the event, the section (with its rounds and the unofficial marker), its tie-breaks and its players: starting rank, name, FIDE ID, title, rating, federation, points, rank and whether they withdrew. Never a birth year, a sex, an account or an email.
{
"event": { "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" },
"section": { "id": "…", "slug": "open", "name": "Open", "source": "trf",
"rounds": 5, "unofficial": false },
"tieBreaks": ["BH", "BH-C1"],
"players": [
{ "startRank": 1, "name": "Perez, Juan", "fideId": "6400000", "title": "GM",
"rating": 2450, "federation": "DOM", "points": 7.5, "rank": 1, "withdrawn": false }
]
}What we never return
The API reads the same public pages the site shows. It holds no personal data beyond what those pages show, and a key is never logged: our logs carry ids only.