API

The official Imperator API

Get started

To get started with the Imperator API, first get an API key by hopping in game and typing /api. Copy this and store it somewhere, you'll need it!

The current rate limit for the API is 60 requests per minute. If you require a larger rate limit, please contact the staff team.

Methods

get
Get server status

https://www.imperator.network/api/status
Check if the server is currently online and how many players are currently playing on it.
Request
Response
Request
Path Parameters
key
required
string
Your API key.
Response
200: OK
{"online":true,"onlinePlayers":0,"maxPlayers":50}
{"online":false}
401: Unauthorized
If you get this, it probably means you forgot to enter your API key.
Unauthorized
429: Too Many Requests
The API has a rate limit of 60 requests per minute.
Too Many Requests

get
Get player data

https://www.imperator.network/api/fetch/player
Retrieves stored player data using either the UUID or the username of the player.
Request
Response
Request
Query Parameters
uuid
optional
string
The UUID of the player.
username
optional
string
The username of the player.
key
required
string
Your API key.
Response
200: OK
May also return as simply null if no data found
{"uuid":"87b2c84b-c062-406e-b646-d3371e04e502","username":"Notch","town":1,"nation":null,"tokens":9999999,"role":"Imperator","joined":"2021-02-26T07:52:54.000Z","paid":false,"deaths":0,"kills":0,"chunks_travelled":0}
400: Bad Request
You probably forgot to enter a username or a UUID!
Bad Request
401: Unauthorized
If you get this, it probably means you forgot to enter your API key.
Unauthorized
429: Too Many Requests
The API has a rate limit of 60 requests per minute.
Too Many Requests

get
Get nation data

https://www.imperator.network/api/fetch/nation
Retrieves stored nation data using either the ID or the name of the nation.
Request
Response
Request
Query Parameters
id
optional
integer
The numerical ID of the nation.
name
optional
string
The name of the nation.
key
required
string
Your API key.
Response
200: OK
May also return as simply null if no data found
{"id":1,"name":"Armenia","longname":"","bank":0,"ideology":"","color":"a38c74","founded":"2021-02-26T07:53:46.000Z","joinable":0,"pollexpiry":6,"proto":true,"members":[{"uuid":"87b2c84b-c062-406e-b646-d3371e04e502","username":"Armenium"}]}
400: Bad Request
You probably forgot to enter a name or a numerical ID!
Bad Request
401: Unauthorized
If you get this, it probably means you forgot to enter your API key.
Unauthorized
429: Too Many Requests
The API has a 60 requests per minute limit.
Too Many Requests

get
Get town data

https://imperator.network/api/fetch/town/
Retrieves stored town data using either the ID or the name of the town.
Request
Response
Request
Query Parameters
name
optional
string
The name of the town.
id
optional
string
The numerical ID of the town.
key
required
string
Your API key.
Response
200: OK
{"id":1,"name":"Yerevan","bank":0,"mayor":"87b2c84b-c062-406e-b646-d3371e04e502","nation":1,"province":null,"permissions":{"build":"Town only","break":"Town only","switch":"Town only","purchasable":"Town only"},"grace":"2021-03-05T07:53:55.000Z"}
400: Bad Request
You probably forgot to enter a name or a numerical ID!
Bad Request
401: Unauthorized
If you get this, it probably means you forgot your API key.
Unauthorized
429: Too Many Requests
The API has a limit of 60 requests per minute.
Too Many Requests

get
Get list of entities in an entity

https://www.imperator.network/api/get/:entities/in/:entity
Request
Response
Request
Path Parameters
entity
required
string
The type of entity that you are looking for that holds the entities of the parameter "entities". Can be "nation", "town", or "province".
entities
required
string
The type of entities that you are looking for that are in a shared entity. Can be "players", "towns", "plots", battles, or provinces.
Query Parameters
id
required
integer
The numerical ID of the nation, province, or town that you are searching for entities inside of.Tt
key
required
string
Your API key.
Response
200: OK
Below is the example for a query on players in a nation.
[{"uuid":"87b2c84b-c062-406e-b646-d3371e04e502","username":"Armenium","town":1,"nation":1,"tokens":9999999,"role":"Imperator","joined":"2021-02-26T07:52:54.000Z","paid":false,"deaths":0,"kills":0,"chunks_travelled":72}]
400: Bad Request
This error can occur for a multitude of reasons; make sure you entered your API key correctly and that you entered the entities and entity type correctly, as well as the numerical ID (which is all required).
Bad Request
401: Unauthorized
If you get this, you probably forgot your key!
Unauthorized
429: Too Many Requests
The API has a limit of 60 requests per minute.
Too Many Requests