API

Kira allows applications to connect directly to it to receive real time updates. This is always based on a single users authentication and the information provided is limited to the one the user has access to.

Obtaining an API token

To obtain an API token, run the command apitoken in Discord. It will generate a token, which gives API access to all snitch alerts and group chat messages of all your groups. Tokens are one time use only and expire after five minutes if not used.

Connecting to Kira

Kira has an open web socket at mc.civclassic.com on port 14314. Upon connecting you are expected to provide the following parameter in the http header:

apiToken is the token you previously obtained from Kira on Discord

applicationId is an identifier unique to your application. It should stay the same for the same application across all users, but may include version information and change with version changes of the application.

apiVersion should always be the value specified here, at the moment 1. It may be used to reject clients expecting an outdated version of the protocol.

Example values for the header could be:

  apiToken: wdfhehscjgbneux
  applicationId: maxopoly-website
  apiVersion: 1

Packet format

All packets sent by Kira are JSON. They all have a field called type which specifies their particular purpose.

Packet list

The following is a list of all packets Kira can send to you

Invalid token

Sent if the API token provided during authentication is not valid. Kira will close the connection immediately after sending this packet

{
  "type": "auth",
  "valid": false
}

Valid token

If the API token provided during authentication is valid, this will be the first packet Kira responds with. It will only be sent once per session.

{
  "type": "auth",
  "valid": true,
  "expires": 1553533645,
  "chats": ["!", "Hjaltland", "Maxopoly"],
  "snitches": ["Hjaltland", "Maxopoly"],
  "skynet": true
}

expires is a UNIX time stamp indicating when the provided token will expire, at which point Kira will stop sending data. If the provided token does not expire, expires will be set to -1

chats is a JSON array containing the names of all groups Kira will send group messages for

snitches is a JSON array containing the names of all groups Kira will send snitch alerts for

skynet is a boolean value indicating whether skynet messages will be sent

Data

There is only one message format for providing data:

{
  "type": "data",
  "group-messages": [...],
  "snitch-alerts": [...],
  "skynet": [...]
}

Each of the three arrays contains JSON objects, which each describe one event. One of these JSON arrays may be missing entirely if no content is available for them. For example the skynet array will only be in the packet if the provided API token included skynet data and logins/logouts happened since the last update.

All event JSONs include a UNIX timestamp field

{
  "time": 1553533645
}

Group message JSONS

Can only be found within the group-messages JSON array in a data packet and describes one group chat message

{
  "time": 1553533645,
  "group": "Hjaltland",
  "player": "Frensin",
  "message": "Hello"
}

group is the name of the group the message was sent to

player is the name of the player who sent the message

message is the message sent

Snitch alert JSONS

Can only be found within the snitch-alerts JSON array in a data packet and describes one snitch alert

{
  "time": 1553533645,
  "player": "Frensin",
  "action": "ENTER",
  "snitch": {
    "location": {
      "x": 1000,
      "y": 64,
      "z": 1000,
      "world": "world_the_end"
    },
    "name": "SecretBase",
    "group": "Hjaltland",
    "type": "ENTRY"
  }
}

location is the location of the snitch

group is the name of the group the snitch is broadcasting to

player is the name of the player who hit the snitch

name is the name of the snitch. May be an empty string if the snitch has no explicit name.

action is one of the following: ENTER, LOGIN or LOGOUT and describes what the player did to cause this alert

type is either LOGGING or ENTRY and describes the type of snitch

Skynet JSONs

Can only be found within the skynet JSON array in a data packet and describes one skynet event

{
  "time": 1553533645,
  "player": "Frensin",
  "action": "LOGIN"
}

player is the name of the player who logged in/out

action is either LOGIN or LOGOUT and describes what the player did