Skip to content

API Definition

Official SDKs

Gate's API definitions are hosted on buf.build/minekube/gate, where you can directly pull client libraries using your preferred language's package manager:

gate_service.proto
protobuf
syntax = "proto3";

package minekube.gate.v1;

// GateService is the service API for managing a Gate proxy instance.
// It provides methods for managing players and servers.
// All methods follow standard gRPC error codes and include detailed error messages.
service GateService {
  // GetPlayer returns the player by the given id or username.
  // Returns NOT_FOUND if the player is not online.
  // Returns INVALID_ARGUMENT if neither id nor username is provided, or if the id format is invalid.
  rpc GetPlayer(GetPlayerRequest) returns (GetPlayerResponse);

  // ListPlayers returns all online players.
  // If servers are specified in the request, only returns players on those servers.
  rpc ListPlayers(ListPlayersRequest) returns (ListPlayersResponse);

  // ListServers returns all registered servers.
  rpc ListServers(ListServersRequest) returns (ListServersResponse);

  // RegisterServer adds a server to the proxy.
  // Returns ALREADY_EXISTS if a server with the same name is already registered.
  // Returns INVALID_ARGUMENT if the server name or address is invalid.
  rpc RegisterServer(RegisterServerRequest) returns (RegisterServerResponse);

  // UnregisterServer removes a server from the proxy.
  // Returns NOT_FOUND if no matching server is found.
  // Returns INVALID_ARGUMENT if neither name nor address is provided.
  rpc UnregisterServer(UnregisterServerRequest) returns (UnregisterServerResponse);

  // ConnectPlayer connects a player to a specified server.
  // Returns NOT_FOUND if either the player or target server doesn't exist.
  // Returns FAILED_PRECONDITION if the connection attempt fails.
  rpc ConnectPlayer(ConnectPlayerRequest) returns (ConnectPlayerResponse);

  // DisconnectPlayer disconnects a player from the proxy.
  // Returns NOT_FOUND if the player doesn't exist.
  // Returns INVALID_ARGUMENT if the reason text is malformed.
  rpc DisconnectPlayer(DisconnectPlayerRequest) returns (DisconnectPlayerResponse);
}

// DisconnectPlayerRequest is the request for DisconnectPlayer method.
message DisconnectPlayerRequest {
  // The player's username or ID to disconnect
  string player = 1;
  // The reason displayed to the player when they are disconnected.
  //
  // Formats:
  //
  // - `{"text":"Hello, world!"}` - JSON text component. See https://wiki.vg/Text_formatting for details.
  //
  // - `§aHello,\n§bworld!` - Simple color codes. See https://wiki.vg/Text_formatting#Colors
  //
  // Optional, if empty no reason will be shown.
  string reason = 2;
}

// DisconnectPlayerResponse is the response for DisconnectPlayer method.
message DisconnectPlayerResponse {}

// ConnectPlayerRequest is the request for ConnectPlayer method.
message ConnectPlayerRequest {
  // The player's username or ID to connect
  string player = 1;
  // The target server name to connect the player to
  string server = 2;
}

// ConnectPlayerResponse is the response for ConnectPlayer method.
message ConnectPlayerResponse {}

// RegisterServerRequest is the request for RegisterServer method.
message RegisterServerRequest {
  // The unique name of the server
  string name = 1;
  // The network address of the server (e.g. "localhost:25565")
  string address = 2;
}

// RegisterServerResponse is the response for RegisterServer method.
message RegisterServerResponse {}

// UnregisterServerRequest is the request for UnregisterServer method.
message UnregisterServerRequest {
  // The name of the server.
  // Optional, if not set, the address will be used to match servers.
  string name = 1;

  // The address of the server.
  // Optional, if not set, the name will be used to match servers.
  // If both name and address are set, only the server that matches both properties exactly will be unregistered.
  // If only the address is set, the first server matching that address will be unregistered.
  string address = 2;
}

// UnregisterServerResponse is the response for UnregisterServer method.
message UnregisterServerResponse {}

// ListServersRequest is the request for ListServers method.
message ListServersRequest {}

// ListServersResponse is the response for ListServers method.
message ListServersResponse {
  repeated Server servers = 1;
}

// Server represents a backend server where Gate can connect players to.
message Server {
  // The unique name of the server.
  string name = 1;
  // The network address of the server.
  string address = 2;
  // The number of players currently on the server.
  int32 players = 3;
}

// GetPlayerRequest is the request for GetPlayer method.
message GetPlayerRequest {
  // Gets the player by their Minecraft UUID.
  // Optional, if not set the username will be used.
  // If both id and username are set, the id will be used.
  // Must be a valid Minecraft UUID format (e.g. "550e8400-e29b-41d4-a716-446655440000")
  string id = 1;
  // Gets the player by their username.
  // Optional, if not set the id will be used.
  // Case-sensitive.
  string username = 2;
}

// GetPlayerResponse is the response for GetPlayer method.
message GetPlayerResponse {
  // The player matching the request criteria
  Player player = 1;
}

// ListPlayersRequest is the request for ListPlayers method.
message ListPlayersRequest {
  // Filter players by server names.
  // Optional, if empty all online players are returned.
  // If specified, only returns players on the listed servers.
  repeated string servers = 1;
}

// ListPlayersResponse is the response for ListPlayers method.
message ListPlayersResponse {
  repeated Player players = 1;
}

// Player represents an online player on the proxy.
message Player {
  // The player's Minecraft UUID
  string id = 1;
  // The player's username
  string username = 2;
}

Protocol Documentation

Table of Contents

Top

minekube/gate/v1/gate_service.proto

ConnectPlayerRequest

ConnectPlayerRequest is the request for ConnectPlayer method.

FieldTypeLabelDescription
playerstringThe player's username or ID to connect
serverstringThe target server name to connect the player to

ConnectPlayerResponse

ConnectPlayerResponse is the response for ConnectPlayer method.

DisconnectPlayerRequest

DisconnectPlayerRequest is the request for DisconnectPlayer method.

FieldTypeLabelDescription
playerstringThe player's username or ID to disconnect
reasonstringThe reason displayed to the player when they are disconnected.

Formats:

Optional, if empty no reason will be shown. |

DisconnectPlayerResponse

DisconnectPlayerResponse is the response for DisconnectPlayer method.

GetPlayerRequest

GetPlayerRequest is the request for GetPlayer method.

FieldTypeLabelDescription
idstringGets the player by their Minecraft UUID. Optional, if not set the username will be used. If both id and username are set, the id will be used. Must be a valid Minecraft UUID format (e.g. "550e8400-e29b-41d4-a716-446655440000")
usernamestringGets the player by their username. Optional, if not set the id will be used. Case-sensitive.

GetPlayerResponse

GetPlayerResponse is the response for GetPlayer method.

FieldTypeLabelDescription
playerPlayerThe player matching the request criteria

ListPlayersRequest

ListPlayersRequest is the request for ListPlayers method.

FieldTypeLabelDescription
serversstringrepeatedFilter players by server names. Optional, if empty all online players are returned. If specified, only returns players on the listed servers.

ListPlayersResponse

ListPlayersResponse is the response for ListPlayers method.

FieldTypeLabelDescription
playersPlayerrepeated

ListServersRequest

ListServersRequest is the request for ListServers method.

ListServersResponse

ListServersResponse is the response for ListServers method.

FieldTypeLabelDescription
serversServerrepeated

Player

Player represents an online player on the proxy.

FieldTypeLabelDescription
idstringThe player's Minecraft UUID
usernamestringThe player's username

RegisterServerRequest

RegisterServerRequest is the request for RegisterServer method.

FieldTypeLabelDescription
namestringThe unique name of the server
addressstringThe network address of the server (e.g. "localhost:25565")

RegisterServerResponse

RegisterServerResponse is the response for RegisterServer method.

Server

Server represents a backend server where Gate can connect players to.

FieldTypeLabelDescription
namestringThe unique name of the server.
addressstringThe network address of the server.
playersint32The number of players currently on the server.

UnregisterServerRequest

UnregisterServerRequest is the request for UnregisterServer method.

FieldTypeLabelDescription
namestringThe name of the server. Optional, if not set, the address will be used to match servers.
addressstringThe address of the server. Optional, if not set, the name will be used to match servers. If both name and address are set, only the server that matches both properties exactly will be unregistered. If only the address is set, the first server matching that address will be unregistered.

UnregisterServerResponse

UnregisterServerResponse is the response for UnregisterServer method.

GateService

GateService is the service API for managing a Gate proxy instance. It provides methods for managing players and servers. All methods follow standard gRPC error codes and include detailed error messages.

Method NameRequest TypeResponse TypeDescription
GetPlayerGetPlayerRequestGetPlayerResponseGetPlayer returns the player by the given id or username. Returns NOT_FOUND if the player is not online. Returns INVALID_ARGUMENT if neither id nor username is provided, or if the id format is invalid.
ListPlayersListPlayersRequestListPlayersResponseListPlayers returns all online players. If servers are specified in the request, only returns players on those servers.
ListServersListServersRequestListServersResponseListServers returns all registered servers.
RegisterServerRegisterServerRequestRegisterServerResponseRegisterServer adds a server to the proxy. Returns ALREADY_EXISTS if a server with the same name is already registered. Returns INVALID_ARGUMENT if the server name or address is invalid.
UnregisterServerUnregisterServerRequestUnregisterServerResponseUnregisterServer removes a server from the proxy. Returns NOT_FOUND if no matching server is found. Returns INVALID_ARGUMENT if neither name nor address is provided.
ConnectPlayerConnectPlayerRequestConnectPlayerResponseConnectPlayer connects a player to a specified server. Returns NOT_FOUND if either the player or target server doesn't exist. Returns FAILED_PRECONDITION if the connection attempt fails.
DisconnectPlayerDisconnectPlayerRequestDisconnectPlayerResponseDisconnectPlayer disconnects a player from the proxy. Returns NOT_FOUND if the player doesn't exist. Returns INVALID_ARGUMENT if the reason text is malformed.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)

Released under the Apache 2.0 License. (web version: 037ca6cf)