Site update

Trackmania 2020 events and input extraction are here!

TM2020 input extraction is now supported, and organizers can create TM2020 events with uploaded maps, dates, custom fields, and collaboration rules.
TMTAS Exchange/Docs/API reference

API reference

API help
Developer reference

Use the REST endpoints below to query tracks and replays, inspect leaderboards, analyze GBX files, and submit authenticated replay uploads.

Current contract These routes are not versioned. Consumers should handle documented errors and avoid assuming undocumented response fields are stable.
Base URLhttps://tmtas.exchange/apiTest ping
Authentication, mutations, and privacy

Public reads require no session unless an endpoint states otherwise. Uploads require an authenticated session. Administrative mutations also require the documented role and same-origin protections. Private event and TAS-of-the-Day data remain subject to server-side visibility rules.

Ping

GET /ping

A simple endpoint to check if the API is responsive.

Returns: A string "POnG".

Example Request:

curl https://tmtas.exchange/api/ping

Tracks

GET /tracks

Retrieves a list of tracks. Supports filtering, sorting, and pagination.

Filtering Parameters:

  • tmx_id: (optional) Filter by TMX ID (default: "0", which means no filtering)
  • exchange: (optional) Filter by exchange (default: "*" for all exchanges, e.g. "tmnf", "tmuf")
  • name: (optional) Filter tracks by name (case-insensitive, partial match)
  • environment: (optional) Filter by environment
    • Accept values: "snow", "desert", "rally", "island", "coast", "bay", "stadium"

Sorting Parameters:

  • sortBy: (optional) Field to sort by (default: "name")
    • Valid options: "name", "exchange", "environment", "tmx_id", "latest_replay_date", "tas_time"
  • sortOrder: (optional) Sort order (default: "asc")
    • Valid options: "asc" (ascending), "desc" (descending)

Pagination Parameters:

  • amount: (optional) Number of results to return (default: 1, max: 50)
  • fromResultIndex: (optional) 1-indexed starting position for pagination (default: 1)

Response Format:

  • results: Array of track objects
  • total: Total number of tracks matching the filter criteria

Example Requests:

Basic query (returns first track, sorted by name):

curl https://tmtas.exchange/api/tracks

Filter by Snow environment, sorted by latest replay date:

curl https://tmtas.exchange/api/tracks?environment=Snow&sortBy=latest_replay_date&sortOrder=desc&amount=10

Get tracks from all exchanges, sorted by fastest TAS time:

curl https://tmtas.exchange/api/tracks?exchange=*&sortBy=tas_time&amount=5

POST /add_track

Adds one TMX track to the exchange. This is an administrator-only, same-origin mutation and is not a public ingestion endpoint.

Authentication and request requirements:

  • An authenticated administrator session is required.
  • The request must pass the platform's same-origin verification.
  • Content-Type must be application/json.
  • Batch track ingestion is not supported by this route.

JSON fields:

  • tmx_id or tmxId: required TMX ID
  • exchange: optional supported exchange identifier

Authenticated same-origin request body:

{
  "tmx_id": 12345,
  "exchange": "tmnf"
}

Suggest

GET /tracks/suggest

Typeahead search suggestions for track names. Returns up to 8 matching tracks.

Query Parameters:

  • q: (required) Search query string (minimum 2 characters)

Response Format:

Returns an array of objects (max 8) with the following fields:

  • name: Track name
  • exchange: Exchange the track belongs to
  • tmx_id: TMX ID of the track

Example Request:

curl https://tmtas.exchange/api/tracks/suggest?q=island

Leaderboards

GET /leaderboard

Retrieves the main leaderboard for a specific track.

Query Parameters:

  • track_id: (required) The ID of the track
  • amount: (optional) Number of results to return (default: 50, max: 50)

Example Request:

curl https://tmtas.exchange/api/leaderboard?track_id=123&amount=10

GET /leaderboardCategories

Retrieves leaderboards for all categories of a specific track.

Query Parameters:

  • track_id: (required) The ID of the track
  • amount: (optional) Number of results to return (default: 50, max: 50)

Example Request:

curl https://tmtas.exchange/api/leaderboardCategories?track_id=123&amount=10

Replays

GET /replays

Retrieves a lightweight list of matching replays. This endpoint always returns at most 500 results and does not expose full replay metadata like /replayData.

Query Parameters:

  • track_id: (optional) Filter by internal track ID
  • tmx_id: (optional) Filter by TMX track ID
  • minReplayTime: (optional) Minimum replay time in milliseconds
  • maxReplayTime: (optional) Maximum replay time in milliseconds
  • minDate: (optional) Minimum replay date as a Unix timestamp
  • maxDate: (optional) Maximum replay date as a Unix timestamp

At least one filter parameter is required. Results are sorted by newest first.

Response Fields:

  • id: Replay ID
  • track_id: Internal track ID
  • tmx_id: TMX track ID
  • time: Replay time in milliseconds
  • date: Replay upload date as a Unix timestamp
  • author: Comma-separated author names, if available

Example Requests:

curl "https://tmtas.exchange/api/replays?track_id=123"
curl "https://tmtas.exchange/api/replays?tmx_id=456&minReplayTime=25000&maxReplayTime=26000"
curl "https://tmtas.exchange/api/replays?minDate=1711929600&maxDate=1714607999"

GET /replay

Downloads a replay file (.gbx) as an attachment.

Query Parameters:

  • id: (required) The ID of the replay

Example Request:

curl https://tmtas.exchange/api/replay?id=123 -o replay.gbx

POST /get_replay

Analyzes a replay file (.gbx) and returns metadata.

Request Body:

  • The .gbx replay file as binary data

Example Request:

curl -X POST https://tmtas.exchange/api/get_replay \
--data-binary @/path/to/your/replay.gbx

GET /replayData

Retrieves replay metadata and, optionally, formatted player inputs.

Query Parameters:

  • id: (required) The ID of the replay
  • inputs: (optional) Set to "true" to include player inputs

Example Request (Metadata only):

curl https://tmtas.exchange/api/replayData?id=123

Example Request (with Inputs):

curl https://tmtas.exchange/api/replayData?id=123&inputs=true

Users

GET /users

Retrieves a list of all registered users.

Example Request:

curl https://tmtas.exchange/api/users

Categories

GET /categories

Retrieves a list of all available run categories.

Example Request:

curl https://tmtas.exchange/api/categories

Upload

POST /upload

Uploads a new TAS replay. Requires authentication via cookie. The request body must be `multipart/form-data`.

Form Fields:

  • replay: The .gbx replay file
  • authors: JSON string of authors. Format: `[{"name": "user1"}]` for unregistered users or `[{"id": "123"}]` for registered users
  • categories: JSON string of run categories. Available categories: "Vanilla", "NOseboost", "Unrestricted", "LIS"
  • routeTypes: (optional) JSON string of route type flags. Available route types: "No Cut", "WR Route"
  • date: (optional) Date of the replay
  • exchange: (optional) The exchange to use (default: "*")
  • videoUrl: (optional) URL to a video of the TAS run (must use http or https)
  • timestamp: (optional) When the TAS starts in the video (format: mm:ss or seconds, e.g. "1:30" or "90")

Authentication:

Requires the `auth-session` cookie for authentication.

Example Request:

curl -X POST https://tmtas.exchange/api/upload \
-H "Cookie: auth-session=YOUR_SESSION_TOKEN" \
-F "replay=@/path/to/your/replay.gbx" \
-F 'authors=[{"name":"user1"}]' \
-F 'categories={"noseboost":false,"lowInputStrat":false}' \
-F 'routeTypes={"noCut":true,"wrRoute":false}'

Misc

POST /get_track_info

Analyzes a track file (.gbx) and returns its unique ID.

Request Body:

  • The .gbx track file as binary data

Example Request:

curl -X POST https://tmtas.exchange/api/get_track_info \
--data-binary @/path/to/your/track.gbx

POST /detectSO

Analyzes a replay to detect special techniques like Uberbug and Noseboost. Returns detected speedrun options and reasons.

Form Fields:

  • replay: The .gbx replay file

Example Request:

curl -X POST https://tmtas.exchange/api/detectSO \
-F "replay=@/path/to/your/replay.gbx"