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

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. Requires current user to be authenticated. (a.k.a have a valid userid and token value)

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

Tells the SuperTuxKart servers the player has earned an achievement.

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.

WARNING WARNING WARNING

Misusing this API call is against the SuperTuxKart Terms of Service and may result in an IP ban from STKAddons.

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"/>

top-players

Gets the top 10 ranked players.

Arguments

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

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>

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