Skip to content

API

Jump to bottom
Maxopoly edited this page Mar 25, 2019 · 18 revisions

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 TCP socket at mc.civclassic.com on port 14314. Upon connecting you are expected to provide the following payload:

{
  "apiToken": "wdfhehscjgbneux",
  "applicationId": "maxopoly-website"
}

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.

Packet format

All packets sent by Kira consist of a header and a body.

The header consists of the first 4 bytes of the packet and is a signed integer in LSB order. It indicates the length of the body of the packet in bytes (not characters!).

The body is UTF-8 encoded JSON

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

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

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

Clone this wiki locally