Some of our services appear not to be working at the moment.

Our team has been notified, and is working on sorting out the issue.

Documentation for the NetherGames Network REST API

API Host

apiv2.nethergames.org
Rate Limits

Beginning July 29th 2021, we require developers who use the NetherGames API for nonpersonal use (for example, but not limited to, Discord stats bots and statistics tracker websites) to register an application to continue using the API. As such, we have adjusted the rate limit for unauthenticated requests from 1000/hour to 250/hour.
By default, if the Authorization header is omitted or invalid, your IP address is limited to 250 requests every hour. If you're building an application that integrates with our API, please create an API integration. If the Authorization header is set to a valid API token, your IP address is limited to 1000 requests per hour.

API Endpoints

GET /v1/announcements

List the recent game announcements by type.

Request Query Params

The type is required and should be one of "board", "title", or "message".

| Property | Type | Default | Validation |
| -------- | -------- | ------- | ----------- |
| limit | ?integer | 100 | range 1-100 |
| type | string | | |


Successful Response

Board and Message:

An array of content strings.

Title:

Returns an array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| title | string |
| subtitle | string |
| fadeIn | integer |
| duration | integer |
| fadeOut | integer |


GET /v1/announcements/discord

List the recent public Discord announcements.

Request Query Params

| Property | Type | Default | Validation |
| -------- | -------- | ------- | ---------- |
| limit | ?integer | 50 | range 1-50 |


Successful Response

Returns an array of objects with the following shape:

| Property | Type |
| ----------- | ----------------------------------- |
| attachments | array of discord attachment objects |
| author | partial discord user object |
| content | string |
| time | timestamp |


POST /v1/applications

Create a new application. You can create at most 10 applications.

Request Body

| Property | Type |
| ----------- | ------ |
| name | string |
| description | string |


Successful Response

The created application.

GET /v1/applications

List all applications you are authorized to view.

Successful Response

An array of objects with the following shape is returned:

| Property | Type |
| ------------ | ---------- |
| id | string |
| name | string |
| description | string |
| ownerId | string |
| token | string |
| createdAt | timestamp |
| lastActiveAt | ?timestamp |


DELETE /v1/applications/:applicationId

Delete the specified application by its ID.

Successful Response

204 No Content

GET /v1/applications/:applicationId

Get the specified application by its ID.

Successful Response

An object with the following shape is returned:

| Property | Type |
| ------------ | ---------- |
| id | string |
| name | string |
| description | string |
| ownerId | string |
| token | string |
| createdAt | timestamp |
| lastActiveAt | ?timestamp |


PATCH /v1/applications/:applicationId

Update the specified application by its ID.

Request Body

| Property | Type | Comment |
| ----------- | -------- | ---------------------------- |
| name | ?string | |
| description | ?string | |
| regenerate | ?boolean | Rotate the application token |


Successful Response

The updated application.

GET /v1/factions/:name

Get a faction by its name.

Successful Response

| Property | Type |
| -------- | ---------------------- |
| id | integer |
| name | string |
| leader | string |
| strength | integer |
| allies | array of faction names |
| officers | array of player names |
| members | array of player names |


GET /v1/guilds/:name

Get a guild by its name.

Successful Response

| Property | Type |
| -------- | --------------------- |
| name | string |
| leader | string |
| maxSize | integer |
| motd | string |
| tag | string |
| officers | array of player names |
| members | array of player names |


GET /v1/leaderboard

List the leaderboard entries for the specified type.

Request Query Params

| Property | Type | Default | Validation |
| -------- | ----------------- | ------- | ----------------------------- |
| limit | ?integer | 100 | range 1-100 |
| type | LeaderboardType | | |
| column | LeaderboardColumn | | only used for type "game" |
| scope | LeaderboardScope | | only used for type "factions" |


type LeaderboardType = "credits" | "factions" | "game" | "kdr" | "kills" | "parkour" | "voters" | "wins" | "xp"
// For all available columns, specify an invalid value for the column query param when making a request.
type LeaderboardColumn = "bb_doubles_wins" | "bb_solo_wins" | "bb_wins" | "bh_wins" | "br_wins" | "bw_beds_broken" | ...
type LeaderboardScope = "bestStreak" | "kills" | "streak"


Successful Response

Returns an array of objects with the following shape for each type:

Credits:

| Property | Type |
| -------- | ------- |
| player | string |
| credits | integer |


Factions:

If the scope query param is specified, the shape is the following:

| Property | Type |
| ---------------- | ------- |
| player | string |
| {{scope column}} | integer |


Otherwise, top factions are listed:

| Property | Type |
| -------- | ------- |
| name | string |
| leader | string |
| strength | integer |


Game:

| Property | Type |
| --------------- | ------- |
| player | string |
| {{column name}} | integer |


KDR:

| Property | Type |
| -------- | ------- |
| player | string |
| kdr | integer |


Kills:

| Property | Type |
| -------- | ------- |
| player | string |
| kills | integer |


Parkour:

| Property | Type |
| -------- | ------ |
| name | string |
| time | float |


Voters:

| Property | Type |
| -------- | ------- |
| nickname | string |
| votes | integer |


Wins:

| Property | Type |
| -------- | ------- |
| player | string |
| wins | integer |


XP:

| Property | Type |
| -------- | ------- |
| player | string |
| xp | integer |


GET /v1/ping

Get data for the specified Minecraft Bedrock server.

Request Query Params

| Property | Type | Default |
| -------- | ---------------------------- | ------- |
| ip | ip address/hostname (string) | |
| port | integer | 19132 |


Successful Response

Example object:

{
"rinfo": {
"address": "51.89.1.138",
"family": "IPv4",
"port": 19132,
"size": 176
},
"advertise": "MCPE;§r§k§b.§r §o§e§lN§6G§r§7: §bNEW UPDATE EU;440;1.16.210;1785;1790;1364977352939892390;WaterdogPE Proxy;Survival;1;19132;19132;",
"serverId": {
"low": -1469092186,
"high": 317808555,
"unsigned": false
},
"pingId": {
"low": 3110,
"high": 0,
"unsigned": false
},
"game": "MCPE",
"version": "1.16.210",
"name": "§r§k§b.§r §o§e§lN§6G§r§7: §bNEW UPDATE EU",
"cleanName": ". NG: NEW UPDATE EU",
"currentPlayers": "1785",
"maxPlayers": "1790",
"ackId": 3147,
"connected": true
}


GET /v1/players/:username

Get a player by their username.

Successful Response

| Property | Type |
| ------------- | --------------------------- |
| name | string |
| bio | string |
| guild | string |
| level | integer |
| online | boolean |
| statusCredits | integer |
| voteStatus | integer |
| xp | integer |
| ranks | array of rank names |
| rankColors | array of rank colors |
| tier | ?string |
| tierColor | ?string |
| deaths | integer |
| kills | integer |
| wins | integer |
| firstJoin | timestamp |
| lastJoin | timestamp |
| lastSeen | string |
| lastServer | string |
| punishments | array of punishment objects |
| warnings | array of warning objects |
| discordData | mixed object |
| factionData | partial player faction data |
| winsData | mixed object |


GET /v1/players/:username/punishments

List the public punishments for the specified player.

Successful Response

Returns an array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| id | integer |
| type | integer |
| reason | string |
| expires | integer |


GET /v1/players/:username/vote-status

Get the vote status for the specified player.

Successful Response

| Property | Type |
| -------- | ------- |
| status | integer |


enum VoteStatus {
None = 0,
Unclaimed = 1,
Claimed = 2,
}


GET /v1/players/:username/warnings

List the public warnings for the specified player.

Successful Response

Returns an array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| id | string |
| reason | string |
| time | integer |


GET /v1/servers

Get server manager data.

GET /v1/servers/meta

Get server metadata.

Technical Issues

If you believe you may have found an issue with the REST API, please contact NetherGames Support - support@nethergames.org. Your report will be forwarded to the developers.


Questions? Contact our support team here or by clicking the chat button in the bottom right corner.
Was this article helpful?
Cancel
Thank you!