GearN Server | Rest Api references Overview

Rest Api References

Overview

Start by reviewing the following guide to understand the core principles of making API requests in GearN. This approach applies universally to all APIs in the system.

HTTP

POST /api/:postType/:requestType/:role/:operationCode

Parameter	Type	Description
postType	string in rJson \| rMsgPack	Specifies whether the request is sent via JSON (t) or MsgPack (r). See PostType
requestType	string	Indicates which entity is making the request: MasterPlayer, GamePlayer, Character, Group... See RequestType
role	string in admin \| server \| client	Specifies the sender's role: 1 (Admin), 2 (Server), 3 (Client). Some APIs require higher privileges. See RequestRole
operationCode	string	The operation identifier to execute (e.g., authenticate, addFriend, createInventory...) See OperationCode

Request Headers

Name	Description
Auth-Token	A token used to authenticate the user. It is issued after successful login from the client type authenticate (e.g., loginByAccount, loginWithCustomId, etc.) or when an admin logs in via the GearN Dashboard. This token identifies the request sender and determines their access level.
Secret-Key	A secure key used to verify that the request originates from a trusted source, per secret key map with a PermissionRule to GearN server known permission of the who send the request
Game-Id	The unique identifier of the game this request is targeting. GearN uses GameId to isolate data between different games. The request will only affect the game that matches the specified gameId
Content-Type	Specifies the format of the request body. Accepted values: application/json if sending JSON. application/msgpack: if sending binary MsgPack (for more efficient size and parsing)

Request Body

Code	Type	Required	Description
customTags	GNHashtable		Additional metadata that can be attached to any request. Especially useful when working with advanced features such as EventCallbackScript.
...			Other fields vary depending on the type of request. Refer to the specific API documentation for required parameters.

Response Body

200 Ok

Code	Type	Required	Description
returnCode	ReturnCode	true	Additional metadata that can be attached to any request. Especially useful when working with advanced features such as EventCallbackScript. See ReturnCode
debugMessage	string		A developer-oriented message that provides additional context useful for debugging and internal logging. This field is not intended for end-users and may include stack traces, validation failures, or internal error diagnostics.
invalidRequestParameters	InvalidMember[]		Just had data when the returnCode is InvalidRequestParameters.A list of members that failed validation or could not be processed during the request. Each entry typically includes identifying information and an error reason. This is useful for partial success scenarios where some members are accepted and others are rejected. See InvalidMember
parameters	ResponseData		Just had data when the returnCode is Ok. A dynamic set of key-value pairs included in the response to provide additional context or metadata. These parameters may vary depending on the operation and typically contain optional fields such as timestamps, identifiers, or computed values relevant to the result. See ResponseData

ReturnCode

Name	Code	Description
SecretInvalid	-10	Secret token is invalid (removed, expired or does not contains).
MaxSizeRequestReject	-9	Request rejected due to exceeding maximum allowed size.
MaxRequestReject	-8	Request rejected because the number of requests has exceeded the allowed limit per user or IP or exceeds the total number of pending requests the server is waiting to process..
MaxCCUReject	-7	Connection rejected due to exceeding the allowed CCU (Concurrent Users).
OperationNotAuthorized	-6	You are not authorized to perform this operation. Possibly due to missing or invalid token, or insufficient permissions.
InvalidRequestParameters	-5	Request parameters are invalid or missing.
OperationInvalid	-4	The requested operation is invalid or not supported.
InternalServerError	-3	Internal server error. Could be due to an unhandled exception or logic failure.
OperationNotAllow	-2	This operation is not allowed in the current context.
OperationTimeout	-1	The operation timed out. No response received within the expected time.
UnknownError	0	An unknown error occurred. The cause could not be determined.
Ok	1	Success. The operation completed successfully and returned a valid result.

ResponseData

Code	Type	Required	Description
errorCode	ErrorCode		A string that represents the status of the operation. It indicates whether the request was successful or failed due to a specific error condition. See ErrorCode
...			Other fields vary depending on the type of request. Refer to the specific API documentation for required parameters.

PostType

Name	Code	Description
Json	rJson	Send Api request via Json.
MsgPack	rMsgPack	Send Api request via MsgPack.

RequestType

Name	Code	Description
Custom	custom	Send Api request for custom operation request when use custom GearN Server.
Authenticate	authenticate	Manages all user authentication methods, including login via username/password, device ID, social providers (Google, Facebook, Apple), and token refresh operations. See Authenticate
CharacterPlayer	characterPlayer	Manages operations related to character-based gameplay. Includes features like inventory, statistics, tags, groups, and data associated with a player’s in-game character. See CharacterPlayer
Content	content	Provides access to game content metadata such as catalogs, class definitions, localization strings, and versioned data used for content distribution. See Content
GamePlayer	gamePlayer	Handles global player data that is not tied to a specific character. Includes user-level settings, custom data, authentication info, and platform linkage. See GamePlayer
Group	group	Manages player groups or teams. Supports creating, joining, leaving, or modifying group membership and associated group metadata. See Group
Inventory	inventory	Handles server-authoritative inventory operations. Includes item creation, usage, consumption, and validation of inventory-related logic. See Inventory
MasterPlayer	masterPlayer	Provides administrative control over player accounts. Includes actions like resetting data, applying server bans, or inspecting global state of players. See MasterPlayer
StoreInventory	storeInventory	Manages virtual store interactions. Includes purchasing, consuming items, currency exchange, and store validation mechanisms. See StoreInventory
Dashboard	dashboard	Reserved for administrative dashboard-related actions, configuration, monitoring, or runtime tools used by backend or operator panels. See Dashboard
Multiplayer	multiplayer	Supports real-time and asynchronous multiplayer functionality. Includes room/session management, matchmaking ticket, match and multiplayer state operations. See Multiplayer
CloudScript	cloudScript	Executes custom server-side scripts hosted on the cloud. Used to run logic like validation, rule enforcement, or backend automation without client trust. See CloudScript

RequestRole

Name	Code	Description
Admin	admin	Indicates that the request originates from an administrative interface or privileged tool. These requests typically have elevated permissions and are used for operations such as banning players, modifying backend data, or accessing internal diagnostics.
Server	server	Represents trusted requests coming from secure backend services or cloud functions. These requests bypass client-side validation and are used for authoritative actions like validating purchases, adjusting stats, or executing server logic.
Client	client	Designates requests initiated from the player’s device or game client. These requests are subject to authentication, rate limiting, and often restricted in scope to prevent unauthorized access or manipulation.

ErrorCode

Name	Code
Ok	1
AccountNotFound	2
AccountPasswordWrong	3
AccountUsernameExists	4
VerifyTokenError	5
VerifyFailed	6
CharacterPlayerNotFound	7
NotEnoughCurrency	8
KeyNotFound	9
ItemNotFound	10
CatalogIdNotFound	11
GroupNotFound	12
OwnerNotFound	13
ClassIdNotFound	14
MemberNotFound	15
PlayerNotMember	16
GamePlayerNotFound	17
FileNotFound	18
FileNotUpload	19
OwnerTypeNotSupport	20
ItemNotStackable	21
GameNotFound	22
GameIsExists	23
SecretInfoNotFound	24
SecretInfoIsExists	25
ExternalNotLinked	26
ExternalLinkedOtherAccount	27
ExternalLinkedOtherValue	28
MasterPlayerNotFound	29
StoreItemNotFound	30
BuyerNotFound	31
CanNotBuyThisStoreItem	32
ExceptionWhenValidateReceipt	33
StoreInvalid	34
ReceiptInvalid	35
StoreItemHadBeenRemove	36
DisplayNameHasUse	37
PlayerBan	38
MatchmakingTicketNotFound	39
MatchmakingTicketAlreadyCompleted	40
MatchmakingPlayerHasNotJoinedTicket	41
MatchNotFound	42
MatchmakingPlayerHasJoinedOtherTicket	43
MatchmakingQueueNotFound	44
TicketSizeError	45
ExecuteError	46
VersionInvalid	47
EmailInvalid	48
StoreItemHadPurchaseAndNonConsumable	49
StoreItemHadExists	50

InvalidMember

Code	Type	Description
code	string	The parameterCode invalid.
invalidMemberType	InvalidMemberType	The invalid member type of this parameterCode. See InvalidMemberType

InvalidMemberType

Name	Code	Description
UnknownError	1	An unspecified or unexpected error has occurred.
DataRequired	2	A required data field is missing or not provided.
TypeInvalid	3	The data type provided does not match the expected type.
StringNull	4	A string value is null or has not been assigned.
StringMinLength	5	The string value is shorter than the minimum required length.
StringMaxLength	6	The string value exceeds the maximum allowed length.
NumberMinValue	7	The numeric value is less than the minimum allowed value.
NumberMaxValue	8	The numeric value exceeds the maximum allowed value.
NumberMustInt	9	The numeric value must be an integer but is not.
GNHashtableNull	10	The hashtable object is null or not provided.
GNHashtableMinLength	11	The hashtable contains fewer entries than the minimum required.
GNHashtableMaxLength	12	The hashtable contains more entries than the maximum allowed.
GNArrayNull	13	The array object is null or not provided.
GNArrayMinLength	14	The array contains fewer elements than the minimum required.
GNArrayMaxLength	15	The array contains more elements than the maximum allowed.

OperationCode

Name	Code
LoginByAdminAccount	loginByAdminAccount
ChangePasswordAdminAccount	changePasswordAdminAccount
GetGameList	getGameList
GetMasterGameSettings	getMasterGameSettings
SetMasterGameSettings	setMasterGameSettings
CreateAdminAccount	createAdminAccount
RemoveAdminAccount	removeAdminAccount
SetPasswordAdminAccount	setPasswordAdminAccount
SetSecretKeyAdminAccount	setSecretKeyAdminAccount
GetGameInformation	getGameInformation
SetGameInformation	setGameInformation
GetAdminAccountList	getAdminAccountList
CreateGame	createGame
GetServerLog	getServerLog
GetSecretInfoInformation	getSecretInfoInformation
GetSecretInfoList	getSecretInfoList
CreateSecretInfo	createSecretInfo
SetSecretInfoInformation	setSecretInfoInformation
GetUsernameAdminAccount	getUsernameAdminAccount
GetAnalytics	getAnalytics
GetEventCallbackCloudScript	getEventCallbackCloudScript
SetEventCallbackCloudScript	setEventCallbackCloudScript
ResetStatisticsLeaderboard	resetStatisticsLeaderboard
GetBackupStatisticsLeaderboardVersion	getBackupStatisticsLeaderboardVersion
GetServerGameData	getServerGameData
DeleteInDatabase	deleteInDatabase
LoginByAccount	loginByAccount
LoginByAndroidDeviceId	loginByAndroidDeviceId
LoginByApple	loginByApple
LoginByCustomDeviceId	loginByCustomDeviceId
LoginByCustomId	loginByCustomId
LoginByEditorDeviceId	loginByEditorDeviceId
LoginByFacebook	loginByFacebook
LoginByGenericService	loginByGenericService
LoginByGoogle	loginByGoogle
LoginByiOSDeviceId	loginByiOSDeviceId
LoginByLinuxDeviceId	loginByLinuxDeviceId
LoginByMacOSDeviceId	loginByMacOSDeviceId
LoginByWindowsDeviceId	loginByWindowsDeviceId
LoginByWindowsPhoneDeviceId	loginByWindowsPhoneDeviceId
RegisterAccount	registerAccount
LinkAccount	linkAccount
LinkAndroidDeviceId	linkAndroidDeviceId
LinkApple	linkApple
LinkCustomDeviceId	linkCustomDeviceId
LinkCustomId	linkCustomId
LinkEditorDeviceId	linkEditorDeviceId
LinkFacebook	linkFacebook
LinkGenericService	linkGenericService
LinkGoogle	linkGoogle
LinkiOSDeviceId	linkiOSDeviceId
LinkLinuxDeviceId	linkLinuxDeviceId
LinkMacOSDeviceId	linkMacOSDeviceId
LinkWindowsDeviceId	linkWindowsDeviceId
LinkWindowsPhoneDeviceId	linkWindowsPhoneDeviceId
UnlinkAccount	unlinkAccount
UnlinkAndroidDeviceId	unlinkAndroidDeviceId
UnlinkApple	unlinkApple
UnlinkCustomDeviceId	unlinkCustomDeviceId
UnlinkCustomId	unlinkCustomId
UnlinkEditorDeviceId	unlinkEditorDeviceId
UnlinkFacebook	unlinkFacebook
UnlinkGenericService	unlinkGenericService
UnlinkGoogle	unlinkGoogle
UnlinkiOSDeviceId	unlinkiOSDeviceId
UnlinkLinuxDeviceId	unlinkLinuxDeviceId
UnlinkMacOSDeviceId	unlinkMacOSDeviceId
UnlinkWindowsDeviceId	unlinkWindowsDeviceId
UnlinkWindowsPhoneDeviceId	unlinkWindowsPhoneDeviceId
AddSegment	addSegment
RemoveSegment	removeSegment
GetSegment	getSegment
SetTag	setTag
GetTag	getTag
SetDisplayName	setDisplayName
GetDisplayName	getDisplayName
GetTsCreate	getTsCreate
GetIpAddressCreate	getIpAddressCreate
GetTsLastLogin	getTsLastLogin
SetPlayerBan	setPlayerBan
GetPlayerBan	getPlayerBan
SetCountryCode	setCountryCode
GetCountryCode	getCountryCode
ChangeAccountPassword	changeAccountPassword
ResetAccountPassword	resetAccountPassword
SetAvatar	setAvatar
GetAvatar	getAvatar
ChangePlayerCurrency	changePlayerCurrency
GetPlayerCurrency	getPlayerCurrency
ChangePlayerStatistics	changePlayerStatistics
GetPlayerStatistics	getPlayerStatistics
GetStatisticsLeaderboard	getStatisticsLeaderboard
GetStatisticsLeaderboardAroundPlayer	getStatisticsLeaderboardAroundPlayer
SetCustomData	setCustomData
GetCustomData	getCustomData
SetPlayerData	setPlayerData
GetPlayerData	getPlayerData
GetPlayerInformation	getPlayerInformation
GetPlayersWithApple	getPlayersWithApple
GetPlayersWithFacebook	getPlayersWithFacebook
GetPlayersWithGoogle	getPlayersWithGoogle
GetPlayersWithGenericService	getPlayersWithGenericService
GetPlayersWithSegment	getPlayersWithSegment
GetPlayersWithTag	getPlayersWithTag
GetExternal	getExternal
GetCatalogId	getCatalogId
GetOwnerInfo	getOwnerInfo
GetOnlineStatus	getOnlineStatus
RemovePlayerItem	removePlayerItem
RemovePlayerCharacter	removePlayerCharacter
AddPlayerFriend	addPlayerFriend
RemovePlayerFriend	removePlayerFriend
GetPlayerInventory	getPlayerInventory
GetPlayerCharacter	getPlayerCharacter
GetPlayerFriend	getPlayerFriend
GetPlayerGroup	getPlayerGroup
CreateGroup	createGroup
JoinGroup	joinGroup
CreatePlayerItem	createPlayerItem
CreatePlayerCharacter	createPlayerCharacter
GetOwner	getOwner
GetRemoveStatus	getRemoveStatus
ChangeGroupStatistics	changeGroupStatistics
SetGroupData	setGroupData
GetGroupCurrency	getGroupCurrency
ChangeGroupCurrency	changeGroupCurrency
CreateGroupItem	createGroupItem
GetStatisticsLeaderboardAroundGroup	getStatisticsLeaderboardAroundGroup
GetGroupsWithTag	getGroupsWithTag
GetGroupsWithSegment	getGroupsWithSegment
GetGroupStatistics	getGroupStatistics
GetGroupInventory	getGroupInventory
GetGroupData	getGroupData
GetGroupInformation	getGroupInformation
GetMembers	getMembers
ChangeItemStatistics	changeItemStatistics
SetItemData	setItemData
GetItemData	getItemData
GetStatisticsLeaderboardAroundItem	getStatisticsLeaderboardAroundItem
GetItemsWithTag	getItemsWithTag
GetItemsWithSegment	getItemsWithSegment
GetItemStatistics	getItemStatistics
GetItemInformation	getItemInformation
GetAmount	getAmount
GetItemType	getItemType
SetTsLastLogin	setTsLastLogin
SetRemoveStatus	setRemoveStatus
SetAmount	setAmount
RemoveGroup	removeGroup
LeaveGroup	leaveGroup
AddMember	addMember
RemoveMember	removeMember
GetContentData	getContentData
SetContentData	setContentData
GetGroupMessage	getGroupMessage
SendGroupMessage	sendGroupMessage
GetPlayersWithDisplayName	getPlayersWithDisplayName
GetItemsWithDisplayName	getItemsWithDisplayName
GetGroupsWithDisplayName	getGroupsWithDisplayName
SetOwner	setOwner
RemoveGroupItem	removeGroupItem
GetClassId	getClassId
GetStoreItemInformation	getStoreItemInformation
GetStoreItemsWithTag	getStoreItemsWithTag
CreateStoreItem	createStoreItem
RemoveTag	removeTag
BuyStoreItem	buyStoreItem
ValidateAppleAppStoreReceipt	validateAppleAppStoreReceipt
ValidateGooglePlayStoreReceipt	validateGooglePlayStoreReceipt
ValidateFacebookStoreReceipt	validateFacebookStoreReceipt
GetFriendStatisticsLeaderboardAroundPlayer	getFriendStatisticsLeaderboardAroundPlayer
GetFriendStatisticsLeaderboard	getFriendStatisticsLeaderboard
SetEmail	setEmail
GetEmail	getEmail
CreateNewFileUploadInfo	createNewFileUploadInfo
GetFileUploadInfo	getFileUploadInfo
RequestDownloadFileUploadInfo	requestDownloadFileUploadInfo
RemoveFileUploadInfo	removeFileUploadInfo
GetFileUploadInfoList	getFileUploadInfoList
SetStoreItemInformation	setStoreItemInformation
RefreshAuthToken	refreshAuthToken
CancelAllMatchmakingTicket	cancelAllMatchmakingTicket
CancelMatchmakingTicket	cancelMatchmakingTicket
CreateMatchmakingTicket	createMatchmakingTicket
GetMatch	getMatch
GetMatchmakingTicket	getMatchmakingTicket
GetQueueStatistics	getQueueStatistics
JoinMatchmakingTicket	joinMatchmakingTicket
ListMatchmakingTicketsForPlayer	listMatchmakingTicketsForPlayer
GetCurrencyLeaderboard	getCurrencyLeaderboard
ExecuteFunction	executeFunction
GetFunctions	getFunctions
AddFunction	addFunction
EditFunction	editFunction
GetFunction	getFunction
LoginByGooglePlayGameService	loginByGooglePlayGameService
LoginByGameCenter	loginByGameCenter
LinkGooglePlayGameService	linkGooglePlayGameService
LinkGameCenter	linkGameCenter
UnlinkGooglePlayGameService	unlinkGooglePlayGameService
UnlinkGameCenter	unlinkGameCenter
GetPlayersWithGooglePlayGameService	getPlayersWithGooglePlayGameService
GetPlayersWithGameCenter	getPlayersWithGameCenter
GetLastLoginLeaderboard	getLastLoginLeaderboard
GetCreateLeaderboard	getCreateLeaderboard
GetAllMatchmakingTicket	getAllMatchmakingTicket
GetAllMatch	getAllMatch
SendSocketOperationEvent	sendSocketOperationEvent
GetStatisticsLog	getStatisticsLog
GetCurrencyLog	getCurrencyLog
PresentStoreItem	presentStoreItem
GetStoreLog	getStoreLog
SendEmail	sendEmail
SendPushNotification	sendPushNotification
AddPushNotification	addPushNotification
RemovePushNotification	removePushNotification
GetPushNotification	getPushNotification
GetStoreUsed	getStoreUsed
RemoveStoreUsed	removeStoreUsed