Trackmania TAS Exchange API

Welcome to the API documentation. The base URL for all endpoints is https://tmtas.exchange/api.

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 a new track to the exchange using TMX ID.

Query Parameters:

  • tmx_id: (required) The TMX ID of the track to add
  • exchange: (optional) The exchange to use (default: "tmnf")

Can also accept a JSON body with the same parameters.

Example Request:

curl -X POST https://tmtas.exchange/api/add_track?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"