Warning: Keep in mind this API is not yet in its final form and may change at any time. If developing, it is strongly recommended to contact an administrator to ensure your application does not accidentally get flagged for spoofing and to be notified about changes!

API Documentation

The MXKarma API controller is a simple REST-like API.
Some operations (such as submitting new karma scores) require an API key. A separate API key is required for each server. An API key can be used to start a session, which yields you a session key, which is then a required parameter at some operations.
All responses are JSON-serialized objects of the following result:

All API requests should be submitted to https://karma.mania-exchange.com/api2/{methodName}?{parameters}.

POST requests are sometimes used if the data structure is more complex. The content of POST requests are always JSON-serialized.
The content-type has to be set to application/json.

Program flow

When used together with a controller, the following program flow should be followed to ensure performance:

  1. startSession called
  2. activateSession called, if succesfully authed, continue forever with:
    1. saveVotes once per map to import votes from an existing local source. (Optional)
    2. getMapRating once a map starts to get current votes, optinally providing an array of player logins whose votes should be looked up.
    3. getMapRating once one or more players connected to look up their votes. It it recommended to have a timeout between multiple of these calls and cache newly connected players. (Optional)
    4. saveVotes once a map ends (only send changed votes!).

Method documentation

GET startSession


Given server login and some additional information, creates a new session for the specified server. A session key and session seed are returned. The session is not activated at time of creation, this has to be done using the session seed and api key in a following activateSession request.

Return structure

GET activateSession


Given a hash from the api key and session seed, and a session key obtained from startSession, activates the session for write operations. Once a session is succesfully activated, other activated sessions are closed. If a session failed to activate, the session is closed immediately.

Return structure

POST getMapRating


Given a map its unique ID, a gamemode and titlepack, returns the amount of votes and the average vote.
An array of logins can be specified to get the ratings these players made, if any.
In case only the votes result field is important, set the getvotesonly value to true!

POST-content structure
Return structure

POST saveVotes


Given a map, gamemode, titlepack and an array of players who changed or added a new vote, saves the votes.
Note: Only changed votes should be submitted, do not send the whole collection of votes again!
Note: Make sure to call this method at reasonable times, such as once the map ends (EndMap callback) send all changed votes and not at every single vote!
Note: Only a single import per map per server is allowed, the client should track imports made as well!
Note: Only locally saved karma-imports are allowed!

POST-content structure
Return structure


In case of an error, the success field of the return object will be false and data contains the following object:

Error object structure

Possible errors are listed below.

CodeMessage & detailsThrown at
1internal server error
Internal server error.
2invalid session
Session key is invalid (not activated, experied or got disabled).
activateSession, getMapRating, saveVotes
3lacking parameters
Some parameters are not provided.
startSession, activateSession
4invalid api key
API key not found or suspended.
5invalid server
Server not found or suspended.
startSession, activateSession, saveVotes
6server is banned
Server is banned.
7session origin and request mismatch
Cross-server call rejected.
activateSession, getMapRating, saveVotes
8invalid hash
Invalid activation hash provided, session closed.
9session already activated
Session already active.
10unsupported content-type
Unsupported Content-Type.
getMapRating, saveVotes
11too many logins
Too many logins requested.
12invalid format
Invalid JSON or invalid structure.
getMapRating, saveVotes
13votes rejected
Malformed vote request.
14no votes cast - please do not make requests if there are no votes!
No votes cast.
15too many import votes - request a limit raise if needed
Too many imports.
16import rejected
Import rejected.