Table of Contents

• Endpoints
• Reference

All endpoints are available at https://ch.tetr.io/api/.

• General (/general/)
  • Server Statistics (/general/stats)
  • Server Activity (/general/activity)
• Users (/users/)
  • User Info (/users/:user)
  • User Records (/users/:user/records)
  • User Search (/users/search/:query)
  • User Lists (/users/lists/)
    • TETRA LEAGUE Leaderboard (/users/lists/league)
    • TETRA LEAGUE Leaderboard (full export) (/users/lists/league/all)
    • XP Leaderboard (/users/lists/xp)
• Streams (/streams/)
  • Get Stream (/streams/:stream)
• TETRA NEWS (/news/)
  • All Latest News (/news/)
  • Latest News (/news/:stream)

Server Statistics

GET /general/stats

Cache time: 60 seconds

Parameters

None

Query string parameters

None

Return data

Some statistics about the service.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • usercount (int) — The amount of users on the server, including anonymous accounts.
  • usercount_delta (float) — The amount of users created a second (through the last minute).
  • anoncount (int) — The amount of anonymous accounts on the server.
  • totalaccounts (int) — The total amount of accounts ever created (including pruned anons etc.).
  • rankedcount (int) — The amount of ranked (visible in TETRA LEAGUE leaderboard) accounts on the server.
  • replaycount (int) — The amount of replays stored on the server.
  • gamesplayed (int) — The amount of games played across all users, including both off- and online modes.
  • gamesplayed_delta (float) — The amount of games played a second (through the last minute).
  • gamesfinished (int) — The amount of games played across all users, including both off- and online modes, excluding games that were not completed (e.g. retries)
  • gametime (float) — The amount of seconds spent playing across all users, including both off- and online modes.
  • inputs (int) — The amount of keys pressed across all users, including both off- and online modes.
  • piecesplaced (int) — The amount of pieces placed across all users, including both off- and online modes.

Server Activity

GET /general/activity

Cache time: 10 minutes

Parameters

None

Query string parameters

None

Return data

A graph of user activity over the last 2 days. A user is seen as active if they logged in or received XP within the last 30 minutes.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • activity (int[]) — An array of plot points, newest points first.

User Info

GET /users/:user

Cache time: 5 minutes

Parameters

• :user (string or MongoID) required — The lowercase username or user ID to look up.

Query string parameters

None

Return data

An object describing the user in detail.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • user (object) — The requested user:
    • _id (string) — The user's internal ID.
    • username (string) — The user's username.
    • role (string) — The user's role (one of "anon", "user", "bot", "halfmod", "mod", "admin", "sysop", "banned").
    • ts? (string) — When the user account was created. If not set, this account was created before join dates were recorded.
    • botmaster? (string) — If this user is a bot, the bot's operator.
    • badges (object[]) — The user's badges:
      • id (string) — The badge's internal ID, and the filename of the badge icon (all PNGs within /res/badges/)
      • label (string) — The badge's label, shown when hovered.
      • ts? (string) — The badge's timestamp, if shown.
    • xp (float) — The user's XP in points.
    • gamesplayed (int) — The amount of online games played by this user. If the user has chosen to hide this statistic, it will be -1.
    • gameswon (int) — The amount of online games won by this user. If the user has chosen to hide this statistic, it will be -1.
    • gametime (float) — The amount of seconds this user spent playing, both on- and offline. If the user has chosen to hide this statistic, it will be -1.
    • country (string?) — The user's ISO 3166-1 country code, or null if hidden/unknown. Some vanity flags exist.
    • badstanding? (bool) — Whether this user currently has a bad standing (recently banned).
    • supporter (bool) — Whether this user is currently supporting TETR.IO <3
    • supporter_tier (int) — An indicator of their total amount supported, between 0 and 4 inclusive.
    • verified (bool) — Whether this user is a verified account.
    • league (object) — This user's current TETRA LEAGUE standing:
      • gamesplayed (int) — The amount of TETRA LEAGUE games played by this user.
      • gameswon (int) — The amount of TETRA LEAGUE games won by this user.
      • rating (float) — This user's TR (Tetra Rating), or -1 if less than 10 games were played.
      • rank (string) — This user's letter rank. Z is unranked.
      • bestrank (string) — This user's highest achieved rank this season.
      • standing (int) — This user's position in global leaderboards, or -1 if not applicable.
      • standing_local (int) — This user's position in local leaderboards, or -1 if not applicable.
      • next_rank (string?) — The next rank this user can achieve, if they win more games, or null if unranked (or the best rank).
      • prev_rank (string?) — The previous rank this user can achieve, if they lose more games, or null if unranked (or the worst rank).
      • next_at (int) — The position of the best player in the user's current rank, surpass them to go up a rank. -1 if unranked (or the best rank).
      • prev_at (int) — The position of the worst player in the user's current rank, dip below them to go down a rank. -1 if unranked (or the worst rank).
      • percentile (float) — This user's percentile position (0 is best, 1 is worst).
      • percentile_rank (string) — This user's percentile rank, or Z if not applicable.
      • glicko? (float) — This user's Glicko-2 rating.
      • rd? (float) — This user's Glicko-2 Rating Deviation. If over 100, this user is unranked.
      • apm? (float) — This user's average APM (attack per minute) over the last 10 games.
      • pps? (float) — This user's average PPS (pieces per second) over the last 10 games.
      • vs? (float) — This user's average VS (versus score) over the last 10 games.
      • decaying (bool) — Whether this user's RD is rising (has not played in the last week).
    • avatar_revision? (int) — This user's avatar ID. Get their avatar at https://tetr.io/user-content/avatars/{ USERID }.jpg?rv={ AVATAR_REVISION }
    • banner_revision? (int) — This user's banner ID. Get their banner at https://tetr.io/user-content/banners/{ USERID }.jpg?rv={ BANNER_REVISION }. Ignore this field if the user is not a supporter.
    • bio? (string) — This user's "About Me" section. Ignore this field if the user is not a supporter.
    • connections (object) — This user's third party connections:
      • discord? (object) — This user's connection to Discord:
        • id (string) — This user's Discord ID.
        • username (string) — This user's Discord Tag.
    • friend_count (int) — The amount of players who have added this user to their friends list.
    • distinguishment? (object) — This user's distinguishment banner, if any. Must at least have:
      • type (string) — The type of distinguishment banner.

User Records

GET /users/:user/records

Cache time: 15 minutes

Parameters

• :user (string or MongoID) required — The lowercase username or user ID to look up.

Query string parameters

None

Return data

An object describing the user's single player records.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • records (object) — The requested user's ranked records:
    • 40l (object) — The user's 40 LINES record:
      • record (object?) — The user's 40 LINES record data, or null if never played.
      • rank (int?) — The user's rank in global leaderboards, or null if not in global leaderboards.
    • blitz (object) — The user's BLITZ record:
      • record (object?) — The user's BLITZ record data, or null if never played.
      • rank (int?) — The user's rank in global BLITZ leaderboards, or null if not in global leaderboards.
  • zen (object) — The user's ZEN record:
    • level (int) — The user's level in ZEN mode.
    • score (int) — The user's score in ZEN mode.

User Search

GET /users/search/:query

Cache time: 5 minutes

Parameters

• :query (string) required — The Discord ID (snowflake) to look up.

Query string parameters

None

Return data

An object describing the user found, or null if none found.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • user (object?) — The requested user:
    • _id (string) — The user's internal ID.
    • username (string) — The user's username.

TETRA LEAGUE Leaderboard

GET /users/lists/league

Cache time: 10 minutes

Parameters

None

Query string parameters

• after? (float) — The upper bound in TR. Use this to paginate downwards: take the lowest seen TR and pass that back through this field to continue scrolling. 25000 by default.
• before? (float) — The lower bound in TR. Use this to paginate upwards: take the highest seen TR and pass that back through this field to continue scrolling. If set, the search order is reversed (returning the lowest items that match the query)
• limit? (int) — The amount of entries to return, between 1 and 100. 50 by default.
• country? (string) — The ISO 3166-1 country code to filter to. Leave unset to not filter by country.

Return data

An array of users fulfilling the search criteria.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • users (object[]) — The matched users:
    • _id (string) — The user's internal ID.
    • username (string) — The user's username.
    • role (string) — The user's role (one of "anon", "user", "bot", "halfmod", "mod", "admin", "sysop").
    • xp (float) — The user's XP in points.
    • country (string?) — The user's ISO 3166-1 country code, or null if hidden/unknown. Some vanity flags exist.
    • supporter (bool) — Whether this user is currently supporting TETR.IO <3
    • verified (bool) — Whether this user is a verified account.
    • league (object) — This user's current TETRA LEAGUE standing:
      • gamesplayed (int) — The amount of TETRA LEAGUE games played by this user.
      • gameswon (int) — The amount of TETRA LEAGUE games won by this user.
      • rating (float) — This user's TR (Tetra Rating), or -1 if less than 10 games were played.
      • rank (string) — This user's letter rank. Z is unranked.
      • bestrank (string) — This user's highest achieved rank this season.
      • glicko? (float) — This user's Glicko-2 rating.
      • rd? (float) — This user's Glicko-2 Rating Deviation. If over 100, this user is unranked.
      • apm? (float) — This user's average APM (attack per minute) over the last 10 games.
      • pps? (float) — This user's average PPS (pieces per second) over the last 10 games.
      • vs? (float) — This user's average VS (versus score) over the last 10 games.
      • decaying (bool) — Whether this user's RD is rising (has not played in the last week).

TETRA LEAGUE Leaderboard (full export)

GET /users/lists/league/all

Cache time: 1 hour

Parameters

None

Query string parameters

• country? (string) — The ISO 3166-1 country code to filter to. Leave unset to not filter by country.

Return data

An array of all users fulfilling the search criteria. Please do not overuse this.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • users (object[]) — The matched users:
    • _id (string) — The user's internal ID.
    • username (string) — The user's username.
    • role (string) — The user's role (one of "anon", "user", "bot", "halfmod", "mod", "admin", "sysop").
    • xp (float) — The user's XP in points.
    • country (string?) — The user's ISO 3166-1 country code, or null if hidden/unknown. Some vanity flags exist.
    • supporter (bool) — Whether this user is currently supporting TETR.IO <3
    • verified (bool) — Whether this user is a verified account.
    • league (object) — This user's current TETRA LEAGUE standing:
      • gamesplayed (int) — The amount of TETRA LEAGUE games played by this user.
      • gameswon (int) — The amount of TETRA LEAGUE games won by this user.
      • rating (float) — This user's TR (Tetra Rating), or -1 if less than 10 games were played.
      • rank (string) — This user's letter rank. Z is unranked.
      • bestrank (string) — This user's highest achieved rank this season.
      • glicko? (float) — This user's Glicko-2 rating.
      • rd? (float) — This user's Glicko-2 Rating Deviation. If over 100, this user is unranked.
      • apm? (float) — This user's average APM (attack per minute) over the last 10 games.
      • pps? (float) — This user's average PPS (pieces per second) over the last 10 games.
      • vs? (float) — This user's average VS (versus score) over the last 10 games.
      • decaying (bool) — Whether this user's RD is rising (has not played in the last week).

XP Leaderboard

GET /users/lists/xp

Cache time: 10 minutes

Parameters

None

Query string parameters

• after? (float) — The upper bound in XP. Use this to paginate downwards: take the lowest seen XP and pass that back through this field to continue scrolling. Infinite by default.
• before? (float) — The lower bound in XP. Use this to paginate upwards: take the highest seen XP and pass that back through this field to continue scrolling. If set, the search order is reversed (returning the lowest items that match the query)
• limit? (int) — The amount of entries to return, between 1 and 100. 50 by default.
• country? (string) — The ISO 3166-1 country code to filter to. Leave unset to not filter by country.

Return data

An array of users fulfilling the search criteria.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • users (object[]) — The matched users:
    • _id (string) — The user's internal ID.
    • username (string) — The user's username.
    • role (string) — The user's role (one of "anon", "user", "bot", "halfmod", "mod", "admin", "sysop").
    • ts? (string) — When the user account was created. If not set, this account was created before join dates were recorded.
    • country (string?) — The user's ISO 3166-1 country code, or null if hidden/unknown. Some vanity flags exist.
    • supporter (bool) — Whether this user is currently supporting TETR.IO <3
    • verified (bool) — Whether this user is a verified account.
    • xp (float) — The user's XP in points.
    • gamesplayed (int) — The amount of online games played by this user. If the user has chosen to hide this statistic, it will be -1.
    • gameswon (int) — The amount of online games won by this user. If the user has chosen to hide this statistic, it will be -1.
    • gametime (float) — The amount of seconds this user spent playing, both on- and offline. If the user has chosen to hide this statistic, it will be -1.

Get Stream

GET /streams/:stream

Cache time: 1 minute

Parameters

• :stream (string) required — The stream ID to look up.

Query string parameters

None

Return data

The records in this Stream. A Stream is a list of records with a set length. Replays that are not featured in any Stream are automatically pruned.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • records (object[]) — The records in this Stream.

All Latest News

GET /news/

Cache time: 1 second

Parameters

• limit? (int) — The amount of entries to return, between 1 and 100. 25 by default.

Query string parameters

None

Return data

The latest news items in any stream.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • news (object[]) — The latest news items:
    • _id (string) — The item's internal ID.
    • stream (string) — The item's stream.
    • type (string) — The item's type.
    • data (object) — The item's records.
    • ts (string) — The item's creation date.

Latest News

GET /news/:stream

Cache time: 1 minute

Parameters

• :stream (string) required — The news stream to look up (either "global" or "user_{ userID }").
• limit? (int) — The amount of entries to return, between 1 and 100. 25 by default.

Query string parameters

None

Return data

The latest news items in the stream. Use stream "global" for the global news.

• success (bool) — Whether the request was successful.
• error? (string) — If unsuccessful, the reason the request failed.
• cache? (object) — If successful, data about how this request was cached.
• data? (object) — If successful, the requested data:
  • news (object[]) — The latest news items:
    • _id (string) — The item's internal ID.
    • stream (string) — The item's stream.
    • type (string) — The item's type.
    • data (object) — The item's records.
    • ts (string) — The item's creation date.

• Cache Data Structure
• Record Data Structure
• Stream IDs
• News Data Structure

Cache Data Structure

All responses from the TETRA CHANNEL API are cached. With every response, a cache object is made available to view the status of the cache:

• status (string) — Whether the cache was hit. Either "hit", "miss", or "awaited" (resource was already being requested by another client)
• cached_at (int) — When this resource was cached.
• cached_until (int) — When this resource's cache expires.

Record Data Structure

Single player records are saved into Record objects, retrievable through the Get Stream and User Records methods. While these may change in structure drastically, the most important parts of their structure is outlined below:

• _id (string) — The Record's ID. This is NOT the replay ID.
• stream (string) — The Stream this Record belongs to.
• replayid (string) — The ID of the associated replay.
• user (object) — The user who set this Record:
  • _id (string) — The user's internal ID.
  • username (string) — The user's username.
• ts (string) — The time this record was set.
• ismulti? (bool) — If true, this is a multiplayer replay.
• endcontext (object, or object[] in case of multiplayer replays) — The state this replay finished with.

Stream IDs

Stream IDs may be broken up into two or three parts, delimited by underscores:

• the type — The type of Stream. Currently "40l", "blitz", or "any".
• the context — The context of this Stream. Currently "global", "userbest", or "userrecent".
• the identifier — If applicable, additional data. For example, in the case of "userbest" or "userrecent", the user ID.

Some examples:

• 40l_global — the global 40 LINES Stream
• blitz_global — the global BLITZ Stream
• league_userrecent_5e32fc85ab319c2ab1beb07c — user 5e32fc85ab319c2ab1beb07c's latest TETRA LEAGUE matches Stream
• 40l_userbest_5e32fc85ab319c2ab1beb07c — user 5e32fc85ab319c2ab1beb07c's best 40 LINES records Stream
• blitz_userbest_5e32fc85ab319c2ab1beb07c — user 5e32fc85ab319c2ab1beb07c's best BLITZ records Stream
• any_userrecent_5e32fc85ab319c2ab1beb07c — user 5e32fc85ab319c2ab1beb07c's recent mixed records Stream

News Data Structure

News data may be stored in different formats depending on the type of news item. Here's all the types with their data structures.

leaderboard

When a user's new personal best enters a global leaderboard. Seen in the global stream only.

• username (string) — The username of the person who got the leaderboard spot.
• gametype (string) — The game mode played.
• rank (int) — The global rank achieved.
• result (float) — The result (score or time) achieved.
• replayid (string) — The replay's shortID.

personalbest

When a user gets a personal best. Seen in user streams only.

• username (string) — The username of the player.
• gametype (string) — The game mode played.
• result (float) — The result (score or time) achieved.
• replayid (string) — The replay's shortID.

badge

When a user gets a badge. Seen in user streams only.

• username (string) — The username of the player.
• type (string) — The badge's internal ID, and the filename of the badge icon (all PNGs within /res/badges/)
• label (string) — The badge's label.

rankup

When a user gets a new top rank in TETRA LEAGUE. Seen in user streams only.

• username (string) — The username of the player.
• rank (string) — The new rank.

supporter

When a user gets TETR.IO Supporter. Seen in user streams only.

• username (string) — The username of the player.

supporter_gift

When a user is gifted TETR.IO Supporter. Seen in user streams only.

• username (string) — The username of the recipient.