Skip to content

API Specification

Jump to bottom
Lilith edited this page Jul 3, 2023 · 34 revisions

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:

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

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 all currently in-game player objects. (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

"server": {
  "players": [
    "76561198210264393": {
      "isSelf": false,
      "name": "x",
      "steamInfo": {
        "accountName": "x",
        "pfp": "x",
        "steamID": "x",
        "vacBans": "x",
        //...Any Other info you can find
      },
      "gameInfo": {
        "team": "RED"
        "ping": 64,
        "kills": 0,
        "deaths": 0,
        //...
      },
      "tags": ["Friend", "Convicted", "MAC User"],
    },
    {
      //....
    }
  ],
  "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 remoteTag: "Recently Disconnected", "Joining", "Steam Friend", "Same regional DB", "Competitive Player", "MegaAntiCheat Admin" Possible verdict: "none", "cheater", "sus", "trusted", "convict"

user (GET)

Returns all relevant information that the backend has on the requested users.

URL

GET mac/user/v1

Request Form Data

Parameter Type Description Requirement Type
steamID64 list A list of steamID64's to retrieve data on Optional
name list A list of in-game names to retrieve data on Optional

One or both of the optional params may be specified.

Example Request

{
  "steamID64": ["abc", "xyz"],
  "name": ["foo", "bar"],
}

Code:

import requests

base = "..."
params = {"steamID64": ['76561198210264393']}
response = requests.get(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>.steamInfo object an object containing all of the data returned from the steam API on this steam account. Some keys will be renamed. See here for more details.
<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": [
    "abc": {
      "isSelf": false,
      "name": "x",
      "steamInfo": {
        "accountName": "x",
        "pfp": "x",
        "steamID": "x",
        "vacBans": "x",
        //...Any Other info you can find
      },
      "gameInfo": {
        "team": "RED"
        "ping": 64,
        "kills": 0,
        "deaths": 0,
        //...
      },
      "tags": ["Friend", "Convicted", "MAC User"],
    },
    {
      "isSelf": false,
      "name": "foo",
      //....
    }
  ],
  "errors": {
    "xyz": "Player not found in game.",
    "bar": "Player not found in game."
  },
}

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 (POST)

A post 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

POST mac/user/v1

Request Form Data

Parameter Type Description Requirement Type
tag object an object containing an arbitrary number of key-value pairs of steamID64 and updated local tag ('local verdict'). Required

Example Request

{
  "tag": {
    "76561198210264393": "Cheater",
    "76561198782264188": "Bot",
  }
}

Code:

import requests

base = "..."
params = {"tag": {'76561198210264393': "Cheater", '76561198782264188': "Bot"}}
response = requests.post(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.

Clone this wiki locally