API Reference

Upload, analyze, and manage HaxBall replays programmatically. Build integrations, bots, and automated workflows with the MrREPLAY API.

Get API Accesshttps://replay.mrhosthaxball.com/api/v1

Introduction

The MrREPLAY API lets you upload and manage HaxBall replays (.hbr2 files) programmatically. Each uploaded replay is automatically analyzed for statistics, heatmaps, shotmaps, player profiles, and chat messages.

Replays are uploaded through bot accounts — virtual identities you create in the dashboard. Each bot gets its own profile page, username, and avatar. Create up to 3 bot accounts per user.

Upload & Analyze

Auto stats, heatmaps, shotmaps

Token Auth

SHA-256 hashed Bearer tokens

Rate Limited

Per-user daily upload quota

Quick Start — HaxBall Headless

The most common use case is auto-uploading replays from a HaxBall Headless bot. Copy this snippet into your bot — it records every match and posts the replay link in chat with full stats.

Get your API token from the API dashboard.

Add this to your bot code:

javascript

const API_URL = "https://replay.mrhosthaxball.com/api/v1/replays";
const TOKEN = "mrr_your_token";

room.onGameStart = function () {
  room.startRecording();
};

room.onGameStop = function () {
  const recording = room.stopRecording();
  if (!recording) return;

  const form = new FormData();
  form.append("file", new Blob([recording]), "match.hbr2");
  form.append("title", room.getRoomName() + " — " + new Date().toLocaleString());
  form.append("visibility", "public");

  fetch(API_URL, {
    method: "POST",
    headers: { Authorization: "Bearer " + TOKEN },
    body: form,
  })
    .then((res) => res.json())
    .then((data) => {
      if (data.success) {
        const d = data.data;
        room.sendAnnouncement(
          "Replay: " + d.url + " | " + d.scoreRed + "-" + d.scoreBlue + " | " + d.playerCount + " players",
          null,
          0xc9952a,
          "bold"
        );
      }
    })
    .catch(() => {});
};

Auto-Analysis

Every uploaded replay is automatically analyzed — player stats, heatmaps, shotmaps, goals, and chat are extracted instantly. The response includes the full replay URL you can share.

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are generated in the API dashboard and are linked to a specific bot account.

bash

curl https://replay.mrhosthaxball.com/api/v1/replays \
  -H "Authorization: Bearer mrr_your_token_here"

Token Security

Tokens are shown once on creation and cannot be retrieved afterward — only the SHA-256 hash is stored. Tokens use the mrr_ prefix for easy identification in leak scans. Revoke compromised tokens immediately in the dashboard.

Rate Limiting

Upload requests (POST /replays) are rate-limited per user with a daily counter that resets at midnight UTC. GET and DELETE requests are not rate-limited.

Header	Description
X-RateLimit-Limit	Your daily upload quota.
X-RateLimit-Remaining	Uploads remaining today.
X-RateLimit-Reset	Unix timestamp when the counter resets (next midnight UTC).

Endpoints

POST

/replays

RATE LIMITED

Upload Replay

Upload and analyze a .hbr2 replay file. The file is validated (magic number, size, extension), analyzed for statistics, heatmaps, and shotmaps, then stored. Returns replay metadata on success.

Form Data

Parameter	Type	Description
fileREQUIRED	File	.hbr2 replay file (max 10 MB)
title	string	Replay title (max 200 chars). Defaults to filename.
visibility	string	"public" or "private". Defaults to "public".
teamRedName	string	Custom red team name (max 50 chars).
teamBlueName	string	Custom blue team name (max 50 chars).
teamRedLogoUrl	string	URL to red team logo image (http/https only).
teamBlueLogoUrl	string	URL to blue team logo image (http/https only).
folderId	string	12-char hex folder ID to file the replay into.

file — .hbr2 replay file (max 10 MB)

title — Replay title (max 200 chars). Defaults to filename.

visibility — "public" or "private". Defaults to "public".

teamRedName — Custom red team name (max 50 chars).

teamBlueName — Custom blue team name (max 50 chars).

teamRedLogoUrl — URL to red team logo image (http/https only).

teamBlueLogoUrl — URL to blue team logo image (http/https only).

folderId — 12-char hex folder ID to file the replay into.

Request

curl -X POST https://replay.mrhosthaxball.com/api/v1/replays \
  -H "Authorization: Bearer mrr_your_token" \
  -F "[email protected]" \
  -F "title=Colombia vs Brasil" \
  -F "visibility=public"

Response

201 Created

json

{
  "success": true,
  "data": {
    "replayId": "7a4fdd2cef6e",
    "url": "https://replay.mrhosthaxball.com/replay/7a4fdd2cef6e",
    "title": "Colombia vs Brasil",
    "duration": 312.5,
    "scoreRed": 3,
    "scoreBlue": 2,
    "playerCount": 10,
    "matchCount": 1,
    "roomName": "🔴⚪🔵 MrHOST - 1 - Miami 🔵⚪🔴",
    "stadiumName": "Futsal x3 by Hax"
  }
}

GET

/replays

List Replays

List all replays uploaded by the authenticated bot account. Supports pagination and sorting.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1).
limit	integer	Results per page, 1-100 (default: 24).
sort	string	newest, oldest, longest, shortest, most-viewed, most-liked.

page — Page number (default: 1).

limit — Results per page, 1-100 (default: 24).

sort — newest, oldest, longest, shortest, most-viewed, most-liked.

Request

curl "https://replay.mrhosthaxball.com/api/v1/replays?page=1&limit=10&sort=newest" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "replays": [
      {
        "replayId": "7a4fdd2cef6e",
        "title": "Colombia vs Brasil",
        "visibility": "public",
        "duration": 312.5,
        "scoreRed": 3,
        "scoreBlue": 2,
        "playerCount": 10,
        "matchCount": 1,
        "roomName": "🔴⚪🔵 MrHOST - 1 - Miami 🔵⚪🔴",
        "likeCount": 5,
        "viewCount": 42,
        "createdAt": "2026-03-12T04:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

GET

/replays/:id

Get Replay

Get full metadata for a specific replay. Private replays are only accessible by the owner.

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl "https://replay.mrhosthaxball.com/api/v1/replays/7a4fdd2cef6e" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "replayId": "7a4fdd2cef6e",
    "url": "https://replay.mrhosthaxball.com/replay/7a4fdd2cef6e",
    "title": "Colombia vs Brasil",
    "originalFileName": "match.hbr2",
    "visibility": "public",
    "duration": 312.5,
    "totalFrames": 18750,
    "scoreRed": 3,
    "scoreBlue": 2,
    "playerCount": 10,
    "matchCount": 1,
    "roomName": "🔴⚪🔵 MrHOST - 1 - Miami 🔵⚪🔴",
    "stadiumName": "Futsal x3 by Hax",
    "likeCount": 5,
    "viewCount": 42,
    "createdAt": "2026-03-12T04:00:00.000Z",
    "updatedAt": "2026-03-12T04:00:00.000Z"
  }
}

GET

/replays/:id/analysis

Get Analysis

Get the full analysis data for a replay including player stats, goals, events, heatmaps, shotmaps, and chat messages.

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl "https://replay.mrhosthaxball.com/api/v1/replays/7a4fdd2cef6e/analysis" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "header": { "version": 3, "totalFrames": 18750, "duration": 312.5 },
    "playerList": [...],
    "matches": [
      {
        "players": [...],
        "goals": [...],
        "heatmaps": { "combined": "/api/replay/.../image/..." },
        "shotmaps": { "combined": "/api/replay/.../image/..." }
      }
    ],
    "chatMessages": [...],
    "events": [...],
    "combined": { "scoreRed": 3, "scoreBlue": 2, ... }
  }
}

GET

/replays/:id/file

Download File

Download the original .hbr2 binary file. Returns the raw binary with Content-Disposition header for the original filename.

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl -OJ "https://replay.mrhosthaxball.com/api/v1/replays/7a4fdd2cef6e/file" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

text

Binary .hbr2 file
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="match.hbr2"

DELETE

/replays/:id

Delete Replay

Permanently delete a replay and all associated data (likes, views). Only the owner can delete their replays.

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl -X DELETE "https://replay.mrhosthaxball.com/api/v1/replays/7a4fdd2cef6e" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "deleted": true,
    "replayId": "7a4fdd2cef6e"
  }
}

PATCH

/replays/:id

Update Replay

Update a replay's title, visibility, team names, logos, or folder assignment. Only send the fields you want to change. Set logo URLs to null to remove them.

Path & Query Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.
title	string	Replay title (max 200 chars). Defaults to filename.
visibility	string	"public" or "private". Defaults to "public".
teamRedName	string	Custom red team name (max 50 chars).
teamBlueName	string	Custom blue team name (max 50 chars).
teamRedLogoUrl	string	URL to red team logo image (http/https only).
teamBlueLogoUrl	string	URL to blue team logo image (http/https only).
folderId	string	12-char hex folder ID to file the replay into.

id — 12-character hex replay or folder ID.

title — Replay title (max 200 chars). Defaults to filename.

visibility — "public" or "private". Defaults to "public".

teamRedName — Custom red team name (max 50 chars).

teamBlueName — Custom blue team name (max 50 chars).

teamRedLogoUrl — URL to red team logo image (http/https only).

teamBlueLogoUrl — URL to blue team logo image (http/https only).

folderId — 12-char hex folder ID to file the replay into.

Request

curl -X PATCH "https://replay.mrhosthaxball.com/api/v1/replays/7a4fdd2cef6e" \
  -H "Authorization: Bearer mrr_your_token" \
  -H "Content-Type: application/json" \
  -d '{"title": "Finals - Colombia vs Brasil", "visibility": "public"}'

Response

200 OK

json

{
  "success": true,
  "data": {
    "replayId": "7a4fdd2cef6e",
    "url": "https://replay.mrhosthaxball.com/replay/7a4fdd2cef6e",
    "title": "Finals - Colombia vs Brasil",
    "visibility": "public",
    "duration": 312.5,
    "scoreRed": 3,
    "scoreBlue": 2,
    "playerCount": 10,
    "teamRedName": "Colombia",
    "teamBlueName": "Brasil",
    "folderId": null,
    "updatedAt": "2026-03-12T06:00:00.000Z"
  }
}

POST

/replays/batch-move

Batch Move Replays

Move multiple replays to a folder in a single request (max 50). Set folderId to null to unfile replays.

JSON Body

Parameter	Type	Description
replayIdsREQUIRED	string[]	Array of 1-50 replay IDs (12-char hex each).
folderIdREQUIRED	string \| null	12-char hex folder ID to file the replay into.

replayIds — Array of 1-50 replay IDs (12-char hex each).

folderId — 12-char hex folder ID to file the replay into.

Request

curl -X POST "https://replay.mrhosthaxball.com/api/v1/replays/batch-move" \
  -H "Authorization: Bearer mrr_your_token" \
  -H "Content-Type: application/json" \
  -d '{"replayIds": ["7a4fdd2cef6e", "b2c3d4e5f6a7"], "folderId": "a1b2c3d4e5f6"}'

Response

200 OK

json

{
  "success": true,
  "data": {
    "modified": 2,
    "folderId": "a1b2c3d4e5f6"
  }
}

POST

/folders

Create Folder

Create a new folder to organize replays. Supports nested folders via parentId, custom colors, and icon URLs.

JSON Body

Parameter	Type	Description
nameREQUIRED	string	Folder name (1-100 characters).
parentId	string	Parent folder ID for nesting (12-char hex). Omit for root.
visibility	string	"public" or "private". Defaults to "public".
color	string	Hex color code (e.g. "#c9952a").
iconUrl	string	URL to folder icon image (http/https only, max 2048 chars).

name — Folder name (1-100 characters).

parentId — Parent folder ID for nesting (12-char hex). Omit for root.

visibility — "public" or "private". Defaults to "public".

color — Hex color code (e.g. "#c9952a").

iconUrl — URL to folder icon image (http/https only, max 2048 chars).

Request

curl -X POST https://replay.mrhosthaxball.com/api/v1/folders \
  -H "Authorization: Bearer mrr_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tournament Replays", "visibility": "public"}'

Response

201 Created

json

{
  "success": true,
  "data": {
    "folderId": "a1b2c3d4e5f6",
    "name": "Tournament Replays",
    "parentId": null,
    "visibility": "public",
    "color": null,
    "iconUrl": null,
    "createdAt": "2026-03-12T04:00:00.000Z",
    "updatedAt": "2026-03-12T04:00:00.000Z"
  }
}

GET

/folders

List Folders

List all folders owned by the authenticated bot account.

Request

curl "https://replay.mrhosthaxball.com/api/v1/folders" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "folders": [
      {
        "folderId": "a1b2c3d4e5f6",
        "name": "Tournament Replays",
        "parentId": null,
        "visibility": "public",
        "color": "#c9952a",
        "iconUrl": null,
        "createdAt": "2026-03-12T04:00:00.000Z"
      }
    ]
  }
}

PATCH

/folders/:id

Update Folder

Update a folder's name, visibility, color, or icon. Only the fields you send will be changed.

Path & Query Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.
name	string	Folder name (1-100 characters).
visibility	string	"public" or "private". Defaults to "public".
color	string	Hex color code (e.g. "#c9952a").
iconUrl	string	URL to folder icon image (http/https only, max 2048 chars).
parentId	string \| null	Parent folder ID for nesting (12-char hex). Omit for root.

id — 12-character hex replay or folder ID.

name — Folder name (1-100 characters).

visibility — "public" or "private". Defaults to "public".

color — Hex color code (e.g. "#c9952a").

iconUrl — URL to folder icon image (http/https only, max 2048 chars).

parentId — Parent folder ID for nesting (12-char hex). Omit for root.

Request

curl -X PATCH "https://replay.mrhosthaxball.com/api/v1/folders/a1b2c3d4e5f6" \
  -H "Authorization: Bearer mrr_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Season 2 Finals", "visibility": "private"}'

Response

200 OK

json

{
  "success": true,
  "data": {
    "folderId": "a1b2c3d4e5f6",
    "name": "Season 2 Finals",
    "parentId": null,
    "visibility": "private",
    "color": "#c9952a",
    "iconUrl": null,
    "createdAt": "2026-03-12T04:00:00.000Z",
    "updatedAt": "2026-03-12T05:00:00.000Z"
  }
}

DELETE

/folders/:id

Delete Folder

Delete a folder and all its subfolders. Replays inside deleted folders become unfiled (not deleted).

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl -X DELETE "https://replay.mrhosthaxball.com/api/v1/folders/a1b2c3d4e5f6" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "deleted": true,
    "folderId": "a1b2c3d4e5f6",
    "foldersDeleted": 1
  }
}

GET

/folders/:id/replays

List Folder Replays

List all replays inside a specific folder. Supports pagination and sorting.

Path & Query Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.
page	integer	Page number (default: 1).
limit	integer	Results per page, 1-100 (default: 24).
sort	string	newest, oldest, longest, shortest, most-viewed, most-liked.

id — 12-character hex replay or folder ID.

page — Page number (default: 1).

limit — Results per page, 1-100 (default: 24).

sort — newest, oldest, longest, shortest, most-viewed, most-liked.

Request

curl "https://replay.mrhosthaxball.com/api/v1/folders/a1b2c3d4e5f6/replays?page=1&limit=10" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "replays": [
      {
        "replayId": "7a4fdd2cef6e",
        "title": "Colombia vs Brasil",
        "duration": 312.5,
        "scoreRed": 3,
        "scoreBlue": 2,
        "playerCount": 10,
        "folderId": "a1b2c3d4e5f6"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

POST

/folders/:id/icon

Upload Folder Icon

Upload a binary image file as the folder's icon. Accepted formats: PNG, JPEG, WebP, GIF (max 2 MB). Replaces any existing icon.

Form Data

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.
iconREQUIRED	file	Image file (PNG, JPEG, WebP, or GIF, max 2 MB).

id — 12-character hex replay or folder ID.

icon — Image file (PNG, JPEG, WebP, or GIF, max 2 MB).

Request

curl -X POST "https://replay.mrhosthaxball.com/api/v1/folders/a1b2c3d4e5f6/icon" \
  -H "Authorization: Bearer mrr_your_token" \
  -F "[email protected]"

Response

201 Created

json

{
  "success": true,
  "data": {
    "folderId": "a1b2c3d4e5f6",
    "iconUrl": "https://replay.mrhosthaxball.com/api/folder-icon/a1b2c3d4e5f6"
  }
}

DELETE

/folders/:id/icon

Delete Folder Icon

Remove the folder's icon image.

Path Parameters

Parameter	Type	Description
idREQUIRED	string	12-character hex replay or folder ID.

id — 12-character hex replay or folder ID.

Request

curl -X DELETE "https://replay.mrhosthaxball.com/api/v1/folders/a1b2c3d4e5f6/icon" \
  -H "Authorization: Bearer mrr_your_token"

Response

200 OK

json

{
  "success": true,
  "data": {
    "folderId": "a1b2c3d4e5f6",
    "iconUrl": null
  }
}

Response Format

All API responses follow a consistent envelope format. Check the success field to determine if the request succeeded.

Success

json

{
  "success": true,
  "data": {
    "replayId": "7a4fdd2cef6e",
    ...
  }
}

Error

json

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Replay not found."
  }
}

CORS

All API responses include Access-Control-Allow-Origin: * headers. You can call the API from any domain, including browser-side JavaScript.

Error Codes

When a request fails, the response includes an error code and a human-readable message. Use the code for programmatic error handling.

Code	Status	Description
UNAUTHORIZED	401	Missing or invalid Authorization header.
INVALID_TOKEN	401	Token is invalid, revoked, or expired.
BOT_NOT_FOUND	401	The bot account linked to this token was deleted.
API_DISABLED	403	API access has not been enabled for this account.
RATE_LIMIT_EXCEEDED	429	Daily upload limit reached. Resets at midnight UTC.
NO_FILE	400	No file provided in the request body.
FILE_TOO_LARGE	400	File exceeds the 10 MB maximum size.
INVALID_TYPE	400	File is not a .hbr2 replay file.
INVALID_FILE	400	File failed HBR2 magic number validation.
ANALYSIS_FAILED	422	The analysis engine could not process this replay.
NOT_FOUND	404	Replay or folder not found, or not accessible.
INVALID_BODY	400	Missing or invalid JSON request body.
INVALID_NAME	400	Invalid folder name (must be 1-100 characters).
VALIDATION_ERROR	400	One or more fields failed validation.
CREATE_FAILED	422	Folder creation failed (e.g. max folders reached, invalid parent).

UNAUTHORIZED — Missing or invalid Authorization header.

INVALID_TOKEN — Token is invalid, revoked, or expired.

BOT_NOT_FOUND — The bot account linked to this token was deleted.

API_DISABLED — API access has not been enabled for this account.

RATE_LIMIT_EXCEEDED — Daily upload limit reached. Resets at midnight UTC.

NO_FILE — No file provided in the request body.

FILE_TOO_LARGE — File exceeds the 10 MB maximum size.

INVALID_TYPE — File is not a .hbr2 replay file.

INVALID_FILE — File failed HBR2 magic number validation.

ANALYSIS_FAILED — The analysis engine could not process this replay.

NOT_FOUND — Replay or folder not found, or not accessible.

INVALID_BODY — Missing or invalid JSON request body.

INVALID_NAME — Invalid folder name (must be 1-100 characters).

VALIDATION_ERROR — One or more fields failed validation.

CREATE_FAILED — Folder creation failed (e.g. max folders reached, invalid parent).

Ready to build?

Create a bot account, generate an API token, and start uploading replays in minutes.

Get Started Discord