Documentation | RecordRanks

RecordRanks provides a public API for accessing events, contests, rankings, and entering results externally.

Events

To get the list of events, use the endpoint below:

/api/[spaceId]/events

spaceId (optional) = URL slug for the space (this parameter can be omitted to use the default space)

Contests

To get the list of contests, use the endpoint below:

/api/[spaceId]/competitions?eventId=[eventId]&region=[region]

spaceId (optional) = URL slug for the space (this parameter can be omitted to use the default space)
eventId (optional) = ID of an event; only returns contests that have this on the list of events
region (optional)  = region; accepts values: 2 letter country ISO code | "XF" | "XA" | "XE" | "XO" | "XN" | "XS" (continent codes)

To get a specific contest, use the endpoint below:

/api/[spaceId]/competitions/[competitionId]

spaceId (optional) = URL slug for the space (this parameter can be omitted to use the default space)
competitionId      = ID of the contest, found in the URL of the contest page

Rankings

To get the rankings, use the endpoint below:

/api/[spaceId]/results/rankings/[eventId]/[type]/[category]?show=[show]&region=[region]&topN=[topN]

spaceId (optional) = URL slug for the space (this parameter can be omitted to use the default space)
eventId            = ID of the event
type               = "single" for top single rankings; "average" for top average rankings; "all-avg-formats" for top average rankings, including Mo3 and Ao5 formats
category           = record category; accepts values: "competitions" | "meetups" | "online" | "all"
show (optional)    = "persons" for top persons rankings (default); "results" for top results rankings
region (optional)  = region (shows World rankings if omitted); accepts values: 2 letter country ISO code | "XF" | "XA" | "XE" | "XO" | "XN" | "XS" (continent codes)
topN (optional)    = how many top results to return; number between 1 and 100,000; defaults to 100

Results can be entered directly via the API. This can be used to enter results into a RecordRanks instance programmatically from a third-party website or an external data entry device. The schema is mostly the same as the WCA Live API, but a space can be specified and the selection of the competitor is different. You can either use personId, which is the unique numerical ID of the competitor in the database, or wcaId, which is an alphanumeric ID from the WCA website (only relevant for speedcubing competitions). For team events personId should be provided as a string containing comma-separated integers; wcaId should be provided as a string containing comma-separated WCA IDs. The order of the competitors is significant.

API keys can be generated on the API Keys page (accessible via the Mod Dashboard). All access tokens remain valid until the contest is finished or deleted. Once you have a key, authorize your API requests with the x-api-key HTTP header.

Entering a single attempt

POST /api/enter-attempt

JSON payload: {
  // "spaceId": "my_space", // URL slug for the space; defaults to "default"; only required for RR instances with multi-tenancy
  "competitionId": "MyCompetition2023",
  "eventId": "fto",
  "roundNumber": 1,
  // Use one of these two options
  "personId": 1, // or "personId": "1,2,3" for a team event
  // "wcaId": "2005DEMO01", // or "wcaId": "2005DEMO01,2005DEMO02" for a team event
  "attemptNumber": 1,
  "attemptResult": 1025
}

Entering multiple attempts and results

WIP

Healthcheck

To see the current healthcheck status, use the endpoint below:

/api/healthcheck

API Reference