WIP all contents of this page are subject to change.

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

Do:

• Rememberbest-practices when naming API endpoints.
• RememberJSON conventions

• 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

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

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

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

GET mac/game/v1

None

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

{}

Code:

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

{"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"

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

POST mac/user/v1

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

Code:

importrequestsparams= {"users": [123456789,1235463235,892357]}base="..."response=requests.post(f"{base}/mac/user/v1/",params=params )

{"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 aplayers object for each player that was both provided in the payload, and found in the game. And anerrors object for each player that the back-end could not return aplayers object for

A put to theuser 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.

PUT mac/user/v1

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

Code:

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

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

{"errors": {}}

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

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

GET mac/pref/v1

None

{}

Code:

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

Data spec TBC, then this will be updated.

{"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.

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

PUT mac/pref/v1

Any number of keys may be specified in the params.

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

Code:

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

{"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."  }}

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.

GET mac/events/v1

List of allmac namespaced events:

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

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

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

GET mac/history/v1

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

The frontend canPOST 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 acustom object can be provided to execute any arbitrary console command.

POST mac/commands/v1

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

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

Returns the list of PlayerRecords stored on disk

GET mac/playerlist/v1

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

POST mac/smcommand/v1

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