The SuperTuxKart Users API Reference

stk_user_api.md

SuperTuxKart Users API Reference

Since the STK developers never made a reference for their users API, I decided to make my own.

The API URL is: https://online.supertuxkart.net/api/v2/user/<apicall>

The POST format must be in this way: <arg1>=<value>&<arg2>=<value>.... For example, userid=345397&token=xxxxxxxxxxxxxxx

Example of sending a request to STK API

Using curl:

curl -X POST \
 -d "userid=345397&token=xxxxxxxxxxxxxxxxxx" \
 --user-agent "SuperTuxKart/1.4 (Linux)" \ # optional, but recommended.
 https://online.supertuxkart.net/api/v2/user/poll

Using Python (requests)

import requests

headers = {
 "content-type": "application/x-www-form-urlencoded",    # mandatory, or API will just give you errors.
 "user-agent": "SuperTuxKart/1.4 (Linux)"                # again, is optional.
}

API_URL = "https://online.supertuxkart.net/api/v2"

req = requests.get(API_URL + "/user/poll", data="userid=345397&token=xxxxxxxxxxxxxxxxxxx", headers=headers)

print(req.content)

poll

Polls user to ensure authentication, and display notifications such as when a friend joins a server (WebSockets when?)

Arguments

• int userid - User ID
• string token - Token of user

Example response:

<poll success="yes" info="" />

connect

Authenticate user

Arguments

• string username - Username
• string password - Password
• optional bool save-session - Whether to remember user or not (creates permanent token)

Example Response

<connect success="yes" token="xxxxxxxxxxxxxxxxxxxx" username="searinminecraft" realname="searinminecraft" userid="345397" achieved="1 2 3 4 5 6 7 8 9 10 11 12" info=""/>

saved-session

Retrieves session information (username, etc.)

Arguments

• int userid - User ID
• string token - Token of user

Example Response:

<saved-session success="yes" token="xxxxxxxxxxxxxxxxxxxx" username="searinminecraft" realname="searinminecraft" userid="345397" info=""/>

get-friends-list

Retrieves friends list of a user.

Arguments

• int userid - User ID
• string token - Token of User
• int visitingid - The User ID of the user you want to get their friends list. Can be the same as userid

Example Response:

<get-friends-list success="yes" info="" visitingid="345397">
 <friends>
  <friend is_pending="no" online="no" date="2022-07-17 07:39:43">
   <user id="368965" user_name="The_Black_Cat_Hollyleaf"/>
  </friend>
  <friend is_pending="no" online="no" date="2022-08-07 05:04:23">
   <user id="49576" user_name="kimden"/>
  </friend>
 </friends>
</get-friends-list>

If the visitingid is different from userid, it only shows limited information:

<get-friends-list success="yes" info="" visitingid="345397">
 <friends>
  <friend>
   <user id="375997" user_name="ichigo-ojetti"/>
  </friend>
  <friend>
   <user id="372507" user_name="ernugraha"/>
  </friend>
  <friend>
   <user id="368965" user_name="The_Black_Cat_Hollyleaf"/>
  </friend>
 </friends>
</get-friends-list>

get-achievements

Retrives achievements of a user.

Arguments

• int userid - User ID
• string token - Token of User
• int visitingid - The User ID of the user you want to get their achievements. Can be the same as userid

Example Response:

<get-achievements success="yes" info="" visitingid="345397" achieved="1 2 3 4 5 6 7 8 9 10 11 12"/>

get-addon-vote

Retrieves the vote of an addon the current user sent.

Arguments

• int userid - User ID
• string token - Token of User
• string addonid - Addon ID. For example: mod-circuit

Example Response:

When voted on:

<get-addon-vote success="yes" voted="yes" rating="3" info=""/>

If not voted on yet:

<get-addon-vote success="yes" voted="no" rating="-1" info=""/>

set-addon-vote

Casts a vote to an addon

Arguments

• int userid - User ID
• string token - Token of User
• string addonid - Addon ID. For example: mod-circuit
• int rating - Rating value. Decimal values are accepted. Must not exceed 6 or go below 0.

Example Response:

<set-addon-vote success="yes" new-average="1.6304347826087" new-number="23" addon-id="bowling" info=""/>

client-quit

Pings SuperTuxKart Servers to tell the player has quit the game.

Arguments

• int userid - User ID
• string token - Token of user

Example Response:

<client-quit success="yes" info=""/>

disconnect

Deauthenticates user, destroys the session and resets the token.

Arguments

• int userid - User ID
• string token - Token of user

Example Response:

<disconnect success="yes" info=""/>

achieving

Syncs local achievements to SuperTuxKart servers.

Arguments

• int userid - User ID
• string token - Token of user
• list achievement-ids - Achievement(s) the player has earned. In their ID number form. You must not use normal spaces, instead use their url encoded version, which is %20

friend-request

Send a friend request to a player

Arguments

• int userid - User ID
• string token - Token of user
• int friendid - ID of user to send a request to

Example Response:

<friend-request success="yes" info=""/>

accept-friend-request

Accepts an incoming friend request.

Arguments

• int userid - User ID
• string token - Token of user
• int friendid - ID of user to accept

Example Response:

<accept-friend-request success="yes" info=""/>

decline-friend-request

Declines an incoming friend request.

Arguments

• int userid - User ID
• string token - Token of user
• int friendid - ID of user to decline

Example Response:

<decline-friend-request success="yes" info=""/>

cancel-friend-request

Cancels a sent friend request.

Arguments

• int userid - User ID
• string token - Token of user
• int friendid - ID of user to cancel a friend request

Example Response:

<cancel-friend-request success="yes" info=""/>

remove-friend

Remove a friend

Arguments

• int userid - User ID
• string token - Token of user
• int friendid - ID of user remove friend

Example Response:

<remove-friend success="yes" info=""/>

user-search

Search for a user in SuperTuxKart

Arguments

• int userid - User ID
• string token - Token of user
• string search-string - Search keyword

Example Response:

A search for "kimden" results in:

<user-search success="yes" info="" search-string="kimden">
 <users>
  <user id="49576" user_name="kimden"/>
  <user id="352929" user_name="kimden."/>
 </users>
</user-search>

register

Creates an account for STKAddons. Unlike on online.supertuxkart.net, it does not require reCAPTCHA attestation token, effectively bypassing the captcha.

Warning

Misusing this API call is against the SuperTuxKart Terms of Service and may result in certain actions taken against you.

Arguments:

• string username - Username
• string password - Password
• string password-confirm - Password confirmation (Must be the same as password!)
• string realname - Real Name
• string email - Email
• string terms - Determines if user agrees to the SuperTuxKart Terms of Service. The value must be on in order for the request to succeed.

Example Response:

<registration success="yes" info=""/>

It will then send an email to the specified email to activate the account

recover

For account recovery

Arguments:

• string username - Username
• string email - Email used in registration

Example Response:

<recover success="yes" info=""/>

It will then send an email to the specified email for password reset instructions.

change-password

Change password of user

Arguments:

• int userid - ID of user
• string current - Current password
• string new1 - New password
• string new2 - Password confirmation (must be the same value as new1)

Example Response:

<change-password success="yes" info=""/>

get-ranking

Get ranking of user.

Arguments

• int userid - User ID
• string token - Token of User
• int id - Same concept as visitingid. The User ID of the user you want to get their ranking.

Example Response:

If the user has no ranking yet:

<get-ranking success="yes" info="" scores="1300" max-scores="1300" num-races-done="0" raw-scores="4000" rating-deviation="1000" disconnects="0" rank="-1"/>

If user has ranking:

<get-ranking success="yes" info="" scores="630.6653440411751" max-scores="2276.387630577021" num-races-done="39" raw-scores="3330.665344041175" rating-deviation="1000" disconnects="412322137026" rank="4592"/>

To get the disconnect rate like in online.supertuxkart.net, see here

top-players

Gets the top 10 ranked players.

Arguments

• int userid - User ID
• string token - Token of User
• optional int ntop - Defines the amount of top players to return. Defaults to 10, but you can set it to a very high amount to effectively return all players shown in https://online.supertuxkart.net/rankings.php.

Example Response:

<top-players success="yes" info="">
 <players>
  <player username="nascartux-2" scores="7657.051018343762" max-scores="7686.999211052843" num-races-done="2901" raw-scores="7764.397012824206" rating-deviation="135.78199816014822" disconnects="0" rank="1"/>
  <player username="mimiz" scores="7608.833835057674" max-scores="7651.954686723075" num-races-done="1060" raw-scores="7841.301482237427" rating-deviation="177.48921572658446" disconnects="0" rank="2"/>
  <player username="remihb" scores="7403.394040960673" max-scores="7737.632453303215" num-races-done="3252" raw-scores="7409.564099391821" rating-deviation="102.05668614371609" disconnects="0" rank="3"/>
  <player username="Wax-stk" scores="7200.275236442525" max-scores="7775.726439171751" num-races-done="1083" raw-scores="7610.627221224665" rating-deviation="236.78399492738004" disconnects="0" rank="4"/>
  <player username="CrystalTheEevee" scores="6617.824052240317" max-scores="6677.0429712336145" num-races-done="305" raw-scores="6934.104910384785" rating-deviation="205.426952714823" disconnects="0" rank="5"/>
  <player username="LLS" scores="6598.321221149626" max-scores="6697.379956214026" num-races-done="1391" raw-scores="6900.834206951637" rating-deviation="200.83766193400373" disconnects="0" rank="6"/>
  <player username="Haenschen" scores="6351.652495551109" max-scores="6828.968507331748" num-races-done="210" raw-scores="7378.38258979998" rating-deviation="442.2433647496239" disconnects="0" rank="7"/>
  <player username="Le-stig-du-21" scores="6308.569829362183" max-scores="6322.254940985489" num-races-done="546" raw-scores="6361.686425079046" rating-deviation="117.70553190562093" disconnects="2305843009213693952" rank="8"/>
  <player username="George-Calibur" scores="6285.743295645444" max-scores="6428.288991805244" num-races-done="1146" raw-scores="6303.97559881003" rating-deviation="106.07743438819521" disconnects="0" rank="9"/>
  <player username="FabianF" scores="6186.659355399041" max-scores="6868.924612256909" num-races-done="738" raw-scores="6534.386705134331" rating-deviation="215.9091165784304" disconnects="1073741824" rank="10"/>
 </players>
</top-players>

To get the disconnect rate like in online.supertuxkart.net, see here

submit-ranking

Submits ranking to SuperTuxKart Servers. Used exclusively for ranked servers. The account must have the required permission (the same as asking permission to create a ranked server) in order to access the endpoint.

Example Response:

<submit-ranking success="yes" info=""/>

reset-ranking

Resets ranking of user. This is an elevated endpoint, which requires the account to have administrator privileges.

Arguments

• int userid - User ID
• string token - Token of User

Other information

Calculate for disconnect rate percentage for ranking player

Here is an example in Python:

>>> races = 546
>>> disconnects = 2305843009213693952
>>> result = (disconnects.bit_count() / min(races, 64) * 100) if races > 0 else 0
>>> print(round(result, ndigits=2), "%")
1.56 %