API documentation

API Introduction

The RepMastered™ API is a simple HTTP API. You interact with it using HTTP requests.
To identify you in your requests, you must send your authtoken with all requests in the Cookie HTTP header like this:

Your authtoken expires when your login expires (6 months after the first login), in which case login again to get a new authtoken.
Do not share your authtoken with anyone! If you think your authtoken might got compromized, go to the ⚙️Settings page and logout from that session.

General responses

If a request succeeds, the HTTP response status will be HTTP 200 OK.

Requests without a valid authtoken will be denied with HTTP 401 Unauthorized.

API requests are also subject to the request rate limiting, see the Is there a limit how fast I can make requests to the site? question on the ❓FAQ page for details.
Each response contains an X-Ttl HTTP header telling how many seconds left from the current time window, and an X-Rl HTTP header telling how many requests you have left within the window.
If you go over this limit, your requests will be denied with an HTTP 429 Too Many Requests response until the current time window is reset, and a Retry-After HTTP header will also be set to the time you must wait before a new request will be served.

Downloading replays via the API also counts toward your download quota which you can check on the ⚙️Settings page.
Each download response contains an X-Dl-Ttl HTTP header telling when the download window resets in seconds, and an X-Dl-Rem HTTP header telling how many downloads you have left within the current download window after serving the current request (or if it would've been served in case it's denied).
Attempting to download more replays than what fits into the download quota will also result in an HTTP 429 Too Many Requests response, and a Retry-After HTTP header will also be set to the time after which the download window resets.

Replay download API

Both games and replays are identified by unique string IDs. The ID of a game is different than the ID of the game's replay. A game might have multiple replays.

Game IDs are listed on the 📹Games page, replay IDs are included in replay download links.
If you plan to download replays in mass, contact me and I can provide you the list of game IDs. (Be aware that just the list of game IDs is bigger than 1GB!)
The game ID list is a simple CSV document, it has 2 columns: gameID,addedAt. Each line contains a game ID and a timestamp when the game was added, sorted by this timestamp, newest games on top. So if you have a new list, you can tell which new games were added since you last downloaded games.

Download single replays

To download a single replay with a given replay ID, simply issue an HTTP GET request to the following URL:

If the request succeeds (HTTP 200 OK), the response body will be the content of the replay file.
HTTP 404 Not Found will be returned if repID is invalid.

Note that the repID might be preceeded with an arbitrary name separated by a space (which is %20 when URL encoded), e.g. the following URL is also valid to download a specific replay:

Download replays in packs by game IDs

You may download replays in packs, where a pack may contain multiple replays up to 100. You have to issue an HTTP GET request, and you must provide the comma separated list of game IDs in the gids request parameter.

If the request succeeds (HTTP 200 OK), the response body will be a zip archive holding the replays.
If a requested game has multiple replays, (only) the longest replay will be included in the pack.
Invalid game IDs are simply ignored (no error is returned), but they are still counted in the download quota.
The file name (games.zip) may be different but must have .zip extension.

Download replays in packs by replay IDs

You may download replays in packs, where a pack may contain multiple replays up to 100. You have to issue an HTTP GET request, and you must provide the comma separated list of replay IDs in the rids request parameter.

If the request succeeds (HTTP 200 OK), the response body will be a zip archive holding the replays.
Invalid replay IDs are simply ignored (no error is returned), but they are still counted in the download quota.
The file name (games.zip) may be different but must have .zip extension.

Download event replay packs

You may download replay packs of events. A single pack will contain replays of all games of an event. You have to issue an HTTP GET request, and you must provide the event ID in the eid request parameter.

If the request succeeds (HTTP 200 OK), the response body will be a zip archive holding the replays.
HTTP 400 Bad Request will be returned if eventID is not an integer, but otherwise an invalid eventID is simply ignored (no error is returned, but the result pack will be empty).
The file name (event.zip) may be different but must have .zip extension.

Event IDs are listed on the 📅Events page. Event IDs are integers, starting from 1.