API Specification

End Points

WIP all contents of this page are subject to change.

Current API version: v1 (all current endpoints will of the form mac/<endpoint>/v1)

Do:

Remember best-practices when naming API endpoints.
Remember JSON conventions

Terminology

verdicts: one of none/trusted/cheater/sus as set by user, but if masterbase reports convict then override the user setting in all scenarios
tags: entirely separate set of strings. used to display if user is for example a friend, a MAC admin, etc

Steam API Key Renaming

'personaname' gets renamed to 'name'
'avatarfull' gets renamed to 'pfp'
'avatar' gets removed
'avatarmedium' gets removed

Player JSON Object Constraints

steamInfo may be NULL if player steam data hasn't been pulled yet
customData will never be NULL, just empty if no customData present

game (`GET`)

Returns the full game object, including server and lobby details, as well as all players currently in that server/lobby.

URL

GET mac/game/v1

Request Form Data

None

No payload required. This endpoint should be hit every time the player joins a new lobby/game. To update a lobby, use mac/user/v# instead.

Example Request

{
}

Code:

import requests

base = "..."
response = requests.get(f"{base}/mac/game/v1")

Response Parameters

Parameter	Type	Description
players	list	A list of objects of all currently in-game players. (See `mac/user/v1` for info on player objects)
map	string	The current game map
ip	string	The current server IP as returned from `status`.
maxPlayers	integer	The max players allowed in the lobby (this may differ from the actual value)
gamemode	object	The gamemode object, which contains the type (string), matchmaking and vanilla flags

Example Response

{
  "players": [
    {
      "isSelf": false,
      "name": "x",
      "steamID64": "x",
      "steamInfo": {
        "accountName": "x",
        "pfp": "x",
        "pfphash": "x",
        "vacBans": "x",
        "isFriend": true,
        //...Any Other info you can find
      },
      "gameInfo": {
        "team": 3,  // team is an int 0,1,2,3
        "ping": 64,
        "kills": 0,
        "deaths": 0,
        //...
      },
      "customData": { /* Store your own json here! */ },
      "localVerdict": "suspicious",
      "convicted": false,
      "tags": ["Convicted", "MAC Admin"]
    },
    {
      //....
    }
  ],
  "map": "X",
  "ip": "X",
  "hostname": "X",
  "maxPlayers": 32,
  "numPlayers": 17,
  "gamemode": {
    "matchmaking": false,
    "type": "Arena",
    "vanilla": false
  }
}

Response contains server data, game details such as map, IP and gamemode, and a list of every player in the game (including self) Possible tags: "Recently Disconnected", "Joining", "Steam Friend", "Same regional DB", "Competitive Player", "MegaAntiCheat Admin" Possible verdicts: "none", "cheater", "sus", "trusted", "convict"

user (`POST`)

Returns all relevant information that the backend has on provided list of users.

URL

POST mac/user/v1

Request Form Data

Parameter	Type	Description	Requirement Type
users	list	A list of steamID64s to return data on.	Required

Example Request

{
  "users": [123456789, 1235463235, 892357]
}

Code:

import requests

params = {"users": [123456789, 1235463235, 892357]}

base = "..."
response = requests.post(f"{base}/mac/user/v1/", params=params )

Response Parameters

Parameter	Type	Description
players	list	A list of player objects, containing the intersection of the set of players requested and the set of players in the game.
errors	object	An object containing a key-value pair for each steamID64 or name that the backend failed to find data on, and the reason.
<player>.isSelf	bool	If this player object represents the player currently running this client.
<player>.name	string	the in-game name of this player, which may or may not vary from the steam name ('personaname' a.k.a <player>.steamInfo.accountName )
<player>.steamID64	string	the players steamID64
<player>.steamInfo	object OR NULL	an object containing all of the data returned from the steam API on this steam account. Some keys will be renamed (see top of page for info). See here for more details. NOTE: This key may be NULL if player data not returned.
<player>.gameInfo	object	an object containing all of the game data captured by the backend relevant to this player (i.e. team, score, ping)
<player>.tags	list	The set of all tags collated from local, regional and remote, with consideration for tag precedence.

Example Response

{
  "players": [
    {
      "isSelf": false,
      "name": "x",
      "steamID64": "x",
      "steamInfo": {
        "accountName": "x",
        "pfp": "x",
        "pfphash": "x",
        "vacBans": "x",
        "isFriend": true,
        "loccountrycode": "AU",
        "timecreated": 9572357
        // ... Any Other info you can find
      },
      "gameInfo": {
        "team": 3,  // team is an int 0,1,2,3
        "ping": 64,
        "kills": 0,
        "deaths": 0,
        // ...
      },
      "customData": { /* Store your own json here! */ },
      "tags": ["Convicted", "MAC User"]
      "localVerdict": "suspicious",
      "convicted": false,
    },
    {
      // ...
    }
  ]
}

The response shall contain a players object for each player that was both provided in the payload, and found in the game. And an errors object for each player that the back-end could not return a players object for

user (`PUT`)

A put to the user endpoint can be used to update locally stored data on the given user. Most significant is the ability to update the local verdict on any number of given users.

URL

PUT mac/user/v1

Request Form Data

Parameter	Type	Description	Requirement Type
	object	an object keyed by a users steamID64, containing an arbitrary number of namespaced key-value pairs of user persistent data to update.	Required

Example Request

{
  "76561198210264393": {
      "localVerdict": "Suspicious",
      "customData": { /* your custom json here! */ }
  },
  "76561198782264188": {
      "localVerdict": "Suspicious",
      "customData": { /* your custom json here! */ }
  }
}

Code:

import requests

base = "..."
params = {
  "76561198210264393": {
      "localVerdict": "Suspicious",
      "customData": { /* your custom json here! */ }
  },
  "76561198782264188": {
      "localVerdict": "Suspicious,
      "customData": { /* your custom json here! */ }
  }
}
response = requests.put(f"{base}/mac/user/v1", params=params)

The localVerdict object may contain any number of "<steamID64>": "verdict", key-value pairs, to enable bulk updates of the local verdict.

Response Parameters

Parameter	Type	Description
errors	object	an object of key-value pairs of steamID64's and the reason why a given player could not be updated.

Example Response

{
  "errors": {}
}

The response shall contain an errors object that would detail any errors encountered whilst trying to update the specified players stored data.

pref (`GET`)

Returns the full list of locally stored user preferences concern the client (both front-end and back)

URL

GET mac/pref/v1

Request Form Data

None

Example Request

{
}

Code:

import requests

base = "..."
response = requests.get(f"{base}/mac/pref/v1")

Response Parameters

Parameter	Type	Description
internal	object	an object containing all internal prefs created and handled by the MAC official backend
external	object	an object containing all custom/non-mac defined user preferences

Data spec TBC, then this will be updated.

Example Response

{
  "internal": {
    "tf2Directory": ".../Team Fortress 2",
    "rconPassword": "password",
    "steamApiKey": "API_KEY_HERE"
  },
  "external": {
    "customPreference": {...}
  }
}

The response shall be an object containing a set of key-value pairs where the key is the name of the stored user pref, and the value is whatever type is stored under that key (can be literal, string, object or list). These will be distinguised by internal values and external values.

pref (`PUT`)

A post to pref is to update user preferences and settings as interacted with via the front-end client.

URL

PUT mac/pref/v1

Request Form Data

Parameter	Type	Description	Requirement Type
internal	object	an object containing the updated value(s) of the given internal user preference key name(s).	Optional
external	object	an object containing the updated value(s) of the given external user preference key name(s).	Optional

Any number of keys may be specified in the params.

Example Request

{
  "internal": {
    "tf2Directory": ".../Team Fortress 2",
    "rconPassword": "password",
    "steamApiKey": "API_KEY_HERE"
  },
  "external": {
    "customPreference": {...}
  }
}

Code:

import requests

base = "..."
params = {"internal": {"autokick_enabled": True}, "external": {"autokick_interbal": 60}}
response = requests.post(f"{base}/mac/pref/v1", params)

Response Parameters

Parameter	Type	Description
changes	object	An object containing the key-value pairs of keys that were changed, and the value of what they now represent
errors	object	An object containing all of the keys that could not be changed, and the reason why

Example Response

{
  "changes": {
    "internal": {
      "autokick_enabled": True 
    },
    "external": {
      "xyz": "foo bar"
    },
  }
  "errors": {
    /* errors will only ever concern internal prefs as we don't track existance of external prefs */
    "autokick_interbal": "A key of that name does not exist."
  }
}

events (`GET`)

The client opens a get request to this endpoint, which returns an event payload whenever an event occurs (i.e. vote_started, vote_update, vote_ended, lobby_joined, lobby_left). This endpoint opens a HTTP event stream type, which means the backend does not close the connection to the front end, even after a response is returned. This is because the same endpoint hit is used to stream all events back to the front end.

URL

GET mac/events/v1

Response Parameters

Parameter	Type	Description
event	string	a key describing the event that has occured, such as "mac:vote_started", or "mac:lobby_joined"
data	object	the event payload data

List of all mac namespaced events:

mac:vote_started
mac:vote_update
mac:vote_finished
mac:lobby_joined
mac:lobby_left

Example Response

{
  "event": "mac:vote_XXXX",
  "data" : { /* event data goes here, such as "yes_votes": 7, "no_votes": 3, etc... */ },
}

history (`GET`)

Returns a list of all the recent players the local client has interacted with, up to the last 100 players. Accepts from= and to= params to query for data within a specific range.

URL

GET mac/history/v1

GET mac/history/v1?from=xyz&to=abc

Response Parameters

Parameter	Type	Description
players	list	A list of player objects, in order of most recently encountered to oldest.

commands (`POST`)

The frontend can POST a list of commands to the backend to execute in the in-game console. A number of commands have dedicated structures for convenience (documented in the example), otherwise a custom object can be provided to execute any arbitrary console command.

URL

POST mac/commands/v1

Request Form Data

Parameter	Type	Description	Requirement Type
commands	object[]	A list containing 0 or more commands to be executed in the in-game console.	Required

Each command object has its own arguments, which are listed below:

Commands available can include:

say[Team]
- Args -> String
- NOTE: The value after the "say" key is a string, not an object
kick
- Args -> userid: string, reason: string
sm_[un]ban
- Args:
- If ban -> player: SteamID64 String, time: u64, reason: string
- If unban -> player: SteamID64 String
sm_kick
- Args -> player: SteamID64 String, reason: string
sm_[un]gag
- Args -> player: SteamID64 String
sm_[un]mute
- Args -> player: SteamID64 String
sm_[un]silence
- Args -> player: SteamID64 String
sm_slay
- Args -> player: SteamID64 String
custom
- Args -> String
- NOTE: The value after the "custom" key is a string, not an object

Example Request

{
  "commands" : [
      { "say" : "Message!" },
      { "sayTeam" : "Team message!" },
      { "kick" : { "player" : "<gameInfo.userid>", "reason": "cheating" } },
      { "custom" : "<Insert command here>" },
      { "sm_ban" : { "player": "76561198210264393", "time": 0, "reason": "Cheating" } }
    ]
}

PlayerList (`GET`)

Returns the list of PlayerRecords stored on disk

URL

GET mac/playerlist/v1

Response Parameters

Parameter	Type	Description
records	list	A list of PlayerRecord objects, as specified on disk.

Example Response

{
  "records" : {
    "path": "/path/to/file/...",
    "<steam id>": {"customdata": {}, "verdict": "<Verdict Enum>"},
    ...
    "<steam id>": {"customdata": {}, "verdict": "<Verdict Enum>"},
  }
}

SMCommand (`POST`) DEPRECATED

URL

POST mac/smcommand/v1

Response Parameters

Parameter	Type	Description
command	str	The command to invoke, one of: [un]ban, kick, [un]gag, [un]mute, [un]silence, slay
target	str	The SteamID64 of the player target of the command
additional_arguments	str[]	A list of additional arguments to provide to the command, in order

Example Payload

{
  "command": "ban",
  "target": "76561198210264393",
  "additional_arguments": ["0", "cheating"],
}

API Specification

End Points

Terminology

Steam API Key Renaming

Player JSON Object Constraints

game (GET)

URL

Request Form Data

Example Request

Response Parameters

Example Response

user (POST)

URL

Request Form Data

Example Request

Response Parameters

Example Response

user (PUT)

URL

Request Form Data

Example Request

Response Parameters

Example Response

pref (GET)

URL

Request Form Data

Example Request

Response Parameters

Example Response

pref (PUT)

URL

Request Form Data

Example Request

Response Parameters

Example Response

events (GET)

URL

Response Parameters

Example Response

history (GET)

URL

Response Parameters

commands (POST)

URL

Request Form Data

Example Request

PlayerList (GET)

URL

Response Parameters

Example Response

SMCommand (POST) DEPRECATED

URL

Response Parameters

Example Payload

Clone this wiki locally

game (`GET`)

user (`POST`)

user (`PUT`)

pref (`GET`)

pref (`PUT`)

events (`GET`)

history (`GET`)

commands (`POST`)

PlayerList (`GET`)

SMCommand (`POST`) DEPRECATED