API docs by Redocly

Venity Network API (2.0.0)

Download OpenAPI specification:Download

Rate Limit: 20 requests/second

Player

Search for a player by name or prefix

path Parameters
name
required
string
Example: John

Player name to search for

query Parameters
prefixSearch
boolean
Default: false

If true, the search will return players whose names start with the given name

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of players to return (maximum is 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get player information by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

Responses

Response samples

Content type
application/json
{
  • "id": 123456,
  • "name": "John",
  • "xuid": "2535418117013099",
  • "coins": 10000,
  • "discordId": "587347873314635839",
  • "crate": 0,
  • "level": 123,
  • "experience": 7619001,
  • "rankName": "default",
  • "guild": {
    },
  • "rankExpiresAt": "2019-08-24T14:15:22Z",
  • "playTime": 1234567,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "lastSeen": "2019-08-24T14:15:22Z",
  • "online": {
    }
}

Get player items by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Game Stats

Get BedWars stats for a player by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

query Parameters
type
string
Default: "lifetime"
Enum: "lifetime" "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "resetAt": "2019-08-24T14:15:22Z",
  • "solo": {
    },
  • "doubles": {
    },
  • "squads": {
    },
  • "bedfightSolo": {
    },
  • "bedfightDoubles": {
    },
  • "fireballfightSolo": {
    },
  • "fireballfightDoubles": {
    },
  • "ironCollected": 0,
  • "goldCollected": 0,
  • "diamondsCollected": 0,
  • "emeraldsCollected": 0
}

Get SkyWars stats for a player by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

query Parameters
type
string
Default: "lifetime"
Enum: "lifetime" "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "resetAt": "2019-08-24T14:15:22Z",
  • "solo": {
    },
  • "doubles": {
    }
}

Get The Bridge stats for a player by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

query Parameters
type
string
Default: "lifetime"
Enum: "lifetime" "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "resetAt": "2019-08-24T14:15:22Z",
  • "solo": {
    },
  • "doubles": {
    }
}

Get Duels stats for a player by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

query Parameters
type
string
Default: "lifetime"
Enum: "lifetime" "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "resetAt": "2019-08-24T14:15:22Z",
  • "solo": {
    },
  • "doubles": {
    }
}

Get CrystalPVP stats for a player by ID

path Parameters
id
required
integer

You can find the player ID in the /v2/player/search/:name endpoint

query Parameters
type
string
Default: "lifetime"
Enum: "lifetime" "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "resetAt": "2019-08-24T14:15:22Z",
  • "duels": {
    },
  • "deathmatch": {
    }
}

Guild

Search for a guild by name or prefix

path Parameters
query
required
string
Example: BebekSquad

Guild name to search for

query Parameters
prefixSearch
boolean
Default: false

If true, the search will return guilds whose names start with the given name

searchBy
string
Default: "tagAndName"
Enum: "name" "tag" "tagAndName"

Search by guild name or tag

limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of guilds to return (maximum is 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get guild information by ID

path Parameters
id
required
integer

You can find the guild ID in the /v2/guild/search/:name endpoint

Responses

Response samples

Content type
application/json
{
  • "id": 123456,
  • "name": "BebekSquad",
  • "tag": "TAG",
  • "level": 5,
  • "experience": 15000,
  • "maxMembers": 20,
  • "members": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Network

Get information about all servers

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get information about all proxies

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get global network information

Responses

Response samples

Content type
application/json
{
  • "onlinePlayers": 250,
  • "dailyUniquePlayers": 5000
}

Leaderboard

Get player leaderboard entries by type

path Parameters
type
required
string
Enum: "game-bedwars-doubles-wins-daily" "game-bedwars-doubles-wins-lifetime" "game-bedwars-doubles-wins-monthly" "game-bedwars-doubles-wins-weekly" "game-bedwars-solo-wins-daily" "game-bedwars-solo-wins-lifetime" "game-bedwars-solo-wins-monthly" "game-bedwars-solo-wins-weekly" "game-bedwars-squads-wins-daily" "game-bedwars-squads-wins-lifetime" "game-bedwars-squads-wins-monthly" "game-bedwars-squads-wins-weekly" "game-bedwars-bedfight_solo-wins-daily" "game-bedwars-bedfight_solo-wins-lifetime" "game-bedwars-bedfight_solo-wins-weekly" "game-bedwars-bedfight_solo-wins-monthly" "game-bedwars-bedfight_doubles-wins-daily" "game-bedwars-bedfight_doubles-wins-lifetime" "game-bedwars-bedfight_doubles-wins-weekly" "game-bedwars-bedfight_doubles-wins-monthly" "game-bedwars-fireballfight_solo-wins-daily" "game-bedwars-fireballfight_solo-wins-lifetime" "game-bedwars-fireballfight_solo-wins-weekly" "game-bedwars-fireballfight_solo-wins-monthly" "game-bedwars-fireballfight_doubles-wins-daily" "game-bedwars-fireballfight_doubles-wins-lifetime" "game-bedwars-fireballfight_doubles-wins-weekly" "game-bedwars-fireballfight_doubles-wins-monthly" "game-crystalpvp-1v1-wins-daily" "game-crystalpvp-1v1-wins-lifetime" "game-crystalpvp-1v1-wins-monthly" "game-crystalpvp-1v1-wins-weekly" "game-crystalpvp-deathmatch-wins-daily" "game-crystalpvp-deathmatch-wins-lifetime" "game-crystalpvp-deathmatch-wins-monthly" "game-crystalpvp-deathmatch-wins-weekly" "game-duels-doubles-wins-daily" "game-duels-doubles-wins-lifetime" "game-duels-doubles-wins-monthly" "game-duels-doubles-wins-weekly" "game-duels-solo-wins-daily" "game-duels-solo-wins-lifetime" "game-duels-solo-wins-monthly" "game-duels-solo-wins-weekly" "game-skywars-doubles-wins-daily" "game-skywars-doubles-wins-lifetime" "game-skywars-doubles-wins-monthly" "game-skywars-doubles-wins-weekly" "game-skywars-solo-wins-daily" "game-skywars-solo-wins-lifetime" "game-skywars-solo-wins-monthly" "game-skywars-solo-wins-weekly" "game-thebridge-doubles-wins-daily" "game-thebridge-doubles-wins-lifetime" "game-thebridge-doubles-wins-monthly" "game-thebridge-doubles-wins-weekly" "game-thebridge-solo-wins-daily" "game-thebridge-solo-wins-lifetime" "game-thebridge-solo-wins-monthly" "game-thebridge-solo-wins-weekly" "game-thebridge-wins-daily" "game-thebridge-wins-lifetime" "game-thebridge-wins-monthly" "game-thebridge-wins-weekly" "player-experience" "player-playtime"

Responses

Response samples

Content type
application/json
{
  • "lastUpdatedAt": "2019-08-24T14:15:22Z",
  • "resetAt": "2019-08-24T14:15:22Z",
  • "entries": [
    ]
}

Get guild leaderboard entries by type

path Parameters
type
required
string
Value: "guild-experience"

Responses

Response samples

Content type
application/json
{
  • "lastUpdatedAt": "2019-08-24T14:15:22Z",
  • "resetAt": "2019-08-24T14:15:22Z",
  • "entries": [
    ]
}

Custom Game

Create a custom game

header Parameters
X-Venity-Custom-Game-Key
required
string
Example: your-venity-custom-game-auth-key

Custom game authentication key. You can request this key from the Venity Network Support at #support on venitymc.com/discord.

Request Body schema: application/json
gameType
string (GameType)
Enum: "BedWars-Solo" "BedWars-Doubles" "BedWars-Squads" "SkyWars-Solo" "SkyWars-Doubles" "Duels-Solo" "Duels-Doubles" "TheBridge-Solo" "TheBridge-Doubles" "CrystalPVP-1v1" "CrystalPVP-Deathmatch" "BedWars-BedFightSolo" "BedWars-BedFightDoubles" "BedWars-FireballFightSolo" "BedWars-FireballFightDoubles"
allowedPlayerIds
Array of integers or null

List of player IDs allowed to join the custom game. If null/empty, the game will be public and anyone can join.

object

Mapping of player IDs to team IDs. If not provided, players will be assigned to teams automatically. -1 means the player is assigned as spectator. The team ID is starting from 0. For example, in BedWars, 0 = Red, 1 = Blue, 2 = Green, 3 = Yellow, etc.

startWhenAllowedPlayersJoined
boolean
Default: false

If true, the game will start automatically when all allowed players have joined. If false, the game will wait for the /v2/custom-game/{id}/start endpoint called.

timeout
integer [ 60 .. 600 ]
Default: 600

If the game is not started within this time (in seconds), it will be automatically cancelled.

region
string
Default: "as"
Enum: "na" "as"

The region where the custom game will be hosted.

Responses

Request samples

Content type
application/json
{
  • "gameType": "BedWars-Solo",
  • "allowedPlayerIds": [
    ],
  • "playerTeamMapping": {
    },
  • "startWhenAllowedPlayersJoined": false,
  • "timeout": 600,
  • "region": "na"
}

Response samples

Content type
application/json
{
  • "gameId": "3f0eee32-8eac-4668-9b38-e3e5dc21d607",
  • "code": "238281"
}

Start a custom game by ID

path Parameters
id
required
string <uuid>

Custom game ID to start

header Parameters
X-Venity-Custom-Game-Key
required
string
Example: your-venity-custom-game-auth-key

Custom game authentication key. You can request this key from the Venity Network Support at #support on venitymc.com/discord.

Responses

Response samples

Content type
application/json
{
  • "message": "Custom game started successfully"
}

Get the status of a custom game by ID

path Parameters
id
required
string <uuid>

Custom game ID to get status for

header Parameters
X-Venity-Custom-Game-Key
required
string
Example: your-venity-custom-game-auth-key

Custom game authentication key. You can request this key from the Venity Network Support at #support on venitymc.com/discord.

Responses

Response samples

Content type
application/json
{
  • "status": "waiting",
  • "playerCount": 0,
  • "serverName": "string"
}

Games

Get recent BedWars games

query Parameters
playerId
integer

You can find the player ID in the /v2/player/search/:name endpoint

after
string <date-time>

Timestamp in ISO 8601 format to filter games after this time.

before
string <date-time>

Timestamp in ISO 8601 format to filter games before this time. Default is the current time.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of games to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get BedWars game details by ID

path Parameters
id
required
string <uuid>

Game ID to retrieve details for

Responses

Response samples

Content type
application/json
{
  • "header": {
    },
  • "participants": [
    ]
}

Get recent SkyWars games

query Parameters
playerId
integer

You can find the player ID in the /v2/player/search/:name endpoint

after
string <date-time>

Timestamp in ISO 8601 format to filter games after this time.

before
string <date-time>

Timestamp in ISO 8601 format to filter games before this time. Default is the current time.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of games to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get SkyWars game details by ID

path Parameters
id
required
string <uuid>

Game ID to retrieve details for

Responses

Response samples

Content type
application/json
{
  • "header": {
    },
  • "participants": [
    ]
}

Get recent CrystalPVP games

query Parameters
playerId
integer

You can find the player ID in the /v2/player/search/:name endpoint

after
string <date-time>

Timestamp in ISO 8601 format to filter games after this time.

before
string <date-time>

Timestamp in ISO 8601 format to filter games before this time. Default is the current time.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of games to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get CrystalPVP game details by ID

path Parameters
id
required
string <uuid>

Game ID to retrieve details for

Responses

Response samples

Content type
application/json
{
  • "header": {
    },
  • "participants": [
    ]
}

Get recent Duels games

query Parameters
playerId
integer

You can find the player ID in the /v2/player/search/:name endpoint

after
string <date-time>

Timestamp in ISO 8601 format to filter games after this time.

before
string <date-time>

Timestamp in ISO 8601 format to filter games before this time. Default is the current time.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of games to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Duels game details by ID

path Parameters
id
required
string <uuid>

Game ID to retrieve details for

Responses

Response samples

Content type
application/json
{
  • "header": {
    },
  • "participants": [
    ]
}

Get recent TheBridge games

query Parameters
playerId
integer

You can find the player ID in the /v2/player/search/:name endpoint

after
string <date-time>

Timestamp in ISO 8601 format to filter games after this time.

before
string <date-time>

Timestamp in ISO 8601 format to filter games before this time. Default is the current time.

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of games to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get TheBridge game details by ID

path Parameters
id
required
string <uuid>

Game ID to retrieve details for

Responses

Response samples

Content type
application/json
{
  • "header": {
    },
  • "participants": [
    ]
}

Legacy API

Get player avatar by name

path Parameters
name
required
string

Responses

Get player skin by name

path Parameters
name
required
string

Responses