PLAY TETRA CHANNEL ABOUT ǹ Ǻ ǻ Ǽ Ǿ
BACK

TETRA CHANNEL REST API

This document outlines the way developers may read player and system data for TETR.IO. This data may be accessed through the API for TETRA CHANNEL.
This document only describes the TETRA CHANNEL API (at https://ch.tetr.io/api/), not the main game API (at https://tetr.io/api/). Usage of the main game API is discouraged at best; you must update your applications to use the TETRA CHANNEL API. Usage of the main game API may put your account in danger.
TETR.IO is in alpha. The API may change without notice between updates. While I hope to keep reverse compatibility as much as possible, things may change every now and then!
Usage of the TETRA CHANNEL API does not require an account or bot account. Please do note that requests are logged. Some simple rules:
  • Do not flood the API with requests. This should be obvious, but just to be sure. Please keep the amount of requests at a moderate rate - once a second should be fine for most cases, short bursts are OK. Please consider other users!
  • Honor caching data. If a response indicates its cache will expire after 10 minutes, please do not rerequest the data during that time, as the data should not change in that time, assuming you are sending an X-Session-ID header.
  • Send an X-Session-ID header if you are often rerequesting the same datasets. This not only assures the data you receive is consistent, it also helps reduce database calls on our side.
  • Don't use a X-Session-ID header for requests that are not related. That way, load balancing can function as expected.
  • Do not use the API in ways that break the TETR.IO Terms of Service. Should be obvious.

Table of Contents

ENDPOINTS

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

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.
    • 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", "mod", "admin").
      • 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
      • 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.
        • 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.
        • 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? (int) — This user's Glicko-2 rating.
        • rd? (int) — 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.
      • 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.

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.

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.
▲ The before and after parameters may not be combined.

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", "mod", "admin").
      • 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.
        • glicko? (int) — This user's Glicko-2 rating.
        • rd? (int) — 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.
● Want to paginate over this data? Remember to pass an X-Session-ID header to ensure data consistency.

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", "mod", "admin").
      • 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.
        • glicko? (int) — This user's Glicko-2 rating.
        • rd? (int) — 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.

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. 25000 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.
▲ The before and after parameters may not be combined.

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", "mod", "admin").
      • 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.
● Want to paginate over this data? Remember to pass an X-Session-ID header to ensure data consistency.

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.

REFERENCE

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.
▲ Cache is not shared between workers. Load balancing may therefore give you unexpected responses. To use the same worker, pass the same X-Session-ID header for all requests that should use the same cache.

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:

▲ This may change any time.
  • _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.
  • endcontext (object) — The state this replay finished with:
    • score (int) — The attained score.
    • piecesplaced (int) — The amount of pieces placed.
    • inputs (int) — The amount of buttons pressed.
    • finalTime (float) — The final time, in milliseconds.
    • gametype (string) — The game mode played.

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
  • 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.

▲ New news types may be added at any moment.

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.