The rest API is used to query karma data for use in third party websites and other kinds of programs.

Versioning

The current version is v1 and all v1 enpoints are under api/v1/

HTTP verbs

Currently all requests that can be done work only using GET requests

Top-Level endpoints

Toplists

This API endpoint is used to retrieve toplists.

GET api/v1/toplists/users

Returns the top 100 users as an Array sorted descending by karma Example reply:

[
  {
    "karma": 123,
    "userId": "293029505457586176",
    "userTag": "TxT#0001"
  }
]

Try it yourself: click me

GET api/v1/toplists/guilds

Returns the top 100 guilds as an Array sorted descending by karma Example reply:

[
  {
    "karma": 123,
    "guildId": "624976691692961793",
    "guildName": "Paxterya",
    "memberCount": 324
  }
]

Try it yourself: click me

History

This API endpoint is used to retrieve historic data.

General

History data should get saved once per hour, but in case of errors this won't be guranteed.

Per default the following endpoints return data of the past 7 days. This can be changed by providing a value in the hoursInPast querystring key. Example with custom hoursInPast: https://karmabot.thetxt.io/api/v1/history/totalkarma?hoursInPast=100

GET api/v1/history/totalkarma

Returns the history of total karma of all users combined. Example reply:

[
  {
    "timestamp": 1607529600380,
    "karma": 169
  }
]

Try it yourself: click me

GET api/v1/history/userkarma/[discord userId]

Returns the history of global karma of specified user. Example reply:

[
  {
    "userId": "293029505457586176",
    "timestamp": 1607529600379,
    "karma": 26
  }
]

Try it yourself: click me

GET api/v1/history/guild/[discord guildId]/totalkarma

Returns the history of karma of specified guild. Example reply:

[
  {
    "guildId": "624976691692961793",
    "timestamp": 1607522400380,
    "karma": 75
  }
]

Try it yourself: click me

GET api/v1/history/guild/[discord guildId]/userkarma/[discord userId]

Returns the history of karma of specified user in specified guild. Example reply:

[
  {
    "userId": "293029505457586176",
    "guildId": "624976691692961793",
    "timestamp": 1607529600380,
    "karma": 22
  }
]

Try it yourself: click me

GET api/v1/history/users/[discord userId]/guildkarma

Returns the history of karma of specified user in all guilds that the user has karma in. Example reply:

[
	{
    "guildkarmaHistory": [
      {
        "userId": "293029505457586176",
        "guildId": "624976691692961793",
        "timestamp": 1608735600591,
        "karma": 30
      }
    ],
     "guildId": "624976691692961793",
     "guildName": "Your cool guild"
  }
]

Try it yourself: click me

GET api/v1/history/usercount

Returns the history of the user count. This counts everyone who received at least one vote as a user Example reply:

[
  {
    "timestamp": 1608332400434,
    "count": 42
  }
]

Try it yourself: click me

GET api/v1/history/guildcount

Returns the history of the guild count. This counts every guild that the bot got ever joined to Example reply:

[
  {
    "timestamp": 1608332400434,
    "count": 42
  }
]

Try it yourself: click me

Users API endpoint

This API endpoint is used to retrieve various, current data about users.

GET api/v1/users/[discord userId]/totalkarma

Returns the current total karma of user Example reply:

[
  {
  "userId": "293029505457586176",
  "totalkarma": 27
  }
]

Try it yourself: click me

GET api/v1/users/[discord userId]/guildkarma

Returns the current guild karma of user. The output contains all guilds the user is currently in. Guilds disabled (by the user) are skipped. Example reply:

[
  {
    "guildkarma": 23,
    "guildId": "624976691692961793",
    "guildName": "Your cool server"
  }
]

Try it yourself: click me

Rank API endpoint

This API endpoint is used to retrieve various, current rank in toplists. Some outputs may not show all information, thats due to the user having disabled certain guilds in their config.

GET api/v1/rank/user/[discord userID]/global

Returns the rank in the global users toplist Example reply:

{
  "userId": "293029505457586176",
  "globalRank": 2
}

Try it yourself: click me

GET api/v1/rank/user/[discord userID]/guild/[discord guildId]/local

Returns the rank in the local users toplist of given guild. Local means that for this rank only karma gained in the given guild counts. Example reply:

{
  "userId": "293029505457586176",
  "guildId": "624976691692961793",
  "guildName": "Your super cool guild",
  "localGuildRank": 1
}

Try it yourself: click me

GET api/v1/rank/user/[discord userID]/guild/[discord guildId]/global

Returns the rank in the local users toplist of given guild. Global means that for this rank all karma counts, but only members of the guild are shown in the output. Example reply:

{
  "userId": "293029505457586176",
  "guildId": "624976691692961793",
  "guildName": "Your super cool guild",
  "globalGuildRank": 2
}

Try it yourself: click me

GET api/v1/rank/user/[discord userID]/guilds/local

Returns the rank in the local users toplist of all guilds. Local means that for this rank only karma gained in the given guild counts. Example reply:

[
  {
    "guildRank": 1,
    "guildId": "624976691692961793",
    "guildName": "Your super cool guild"
  }
]

Try it yourself: click me

GET api/v1/rank/user/[discord userID]/guilds/global

Returns the rank in the local users toplist of all guilds. Global means that for this rank all karma counts, but only members of the guild are shown in the output. Example reply:

[
  {
    "guildRank": 2,
    "guildId": "624976691692961793",
    "guildName": "Your super cool guild"
  }
]

Try it yourself: click me

GET api/v1/rank/guild/[discord guildId]

Returns the rank of the given guild in the guilds toplist. This counts all votes given in the guild. Example reply:

{
  "guildId": "624976691692961793",
  "guildName": "Your super cool guild",
  "rank": 1
}

Try it yourself: click me