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 | Required | Description |
|---|---|---|---|
| postType | string in rJson | rMsgPack | true | Specifies whether the request is sent via JSON (t) or MsgPack (r). See PostType |
| requestType | string | true | Indicates which entity is making the request: MasterPlayer, GamePlayer, Character, Group... See RequestType |
| role | string in admin | server | client | true | Specifies the sender's role: 1 (Admin), 2 (Server), 3 (Client). Some APIs require higher privileges. See RequestRole |
| operationCode | string | true | The operation identifier to execute (e.g., authenticate, addFriend, createInventory...) See OperationCode |
Request Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Auth-Token | string | 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 | string | 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 | string | 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 | string | true | Specifies the format of the request body. Accepted values:
|
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 | The selected secret key is missing, wrong, or does not match the current route/game context. |
| MaxSizeRequestReject | -9 | The serialized request payload exceeded the maximum size accepted by the backend. |
| MaxRequestReject | -8 | The backend rejected the request because the current caller exceeded a request-rate limit. |
| MaxCCUReject | -7 | The backend rejected the request because the current concurrent-user/session limit was exceeded. |
| OperationNotAuthorized | -6 | The target operation exists, but the caller is not authorized for the selected role or target resource. |
| InvalidRequestParameters | -5 | The request shape or one or more request-member values are invalid. When available, inspect `invalidMembers` for field-level details. |
| OperationInvalid | -4 | The requested operation code is unknown or is not valid for the selected request type/role. |
| InternalServerError | -3 | The backend hit an unhandled internal failure before producing a valid business response. |
| OperationNotAllow | -2 | The operation is known and the secret key is valid, but the permission rules attached to the current secret key do not allow this operation in the current target context. This usually maps to missing `selfEnable`, `otherSelfEnable`, `serverSelfEnable`, or `adminSelfEnable` permission for the resolved request. |
| OperationTimeout | -1 | The request timed out before a response was received. This code may be synthesized by the SDK timeout layer as well as returned by the backend. |
| UnknownError | 0 | The request failed, but no more specific low-level return code was mapped. |
| Ok | 1 | The request completed successfully at protocol level and produced a response payload. Callers must still validate the business `errorCode` in that payload. |
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 | Description |
|---|---|---|
| Ok | 1 | The business operation completed successfully. |
| AccountNotFound | 2 | The requested username/account does not exist. |
| AccountPasswordWrong | 3 | The provided account password is incorrect. |
| AccountUsernameExists | 4 | The requested username already exists and cannot be created again. |
| VerifyTokenError | 5 | The provided token could not be verified or decoded. |
| VerifyFailed | 6 | An external/provider verification step failed. |
| CharacterPlayerNotFound | 7 | The target character player does not exist. |
| NotEnoughCurrency | 8 | The target wallet or owner does not have enough currency to complete the operation. |
| KeyNotFound | 9 | The requested key does not exist in the target data set. |
| ItemNotFound | 10 | The target inventory item does not exist. |
| CatalogIdNotFound | 11 | The referenced catalog id does not exist. |
| GroupNotFound | 12 | The target group does not exist. |
| OwnerNotFound | 13 | The resolved owner entity does not exist. |
| ClassIdNotFound | 14 | The referenced class id does not exist. |
| MemberNotFound | 15 | The target group member or relationship member does not exist. |
| PlayerNotMember | 16 | The player is not currently a member of the target group. |
| GamePlayerNotFound | 17 | The target game player does not exist. |
| FileNotFound | 18 | The requested file metadata or physical file does not exist. |
| FileNotUpload | 19 | The file metadata exists but the file content has not been uploaded yet. |
| OwnerTypeNotSupport | 20 | The requested owner type is not supported by the target operation. |
| ItemNotStackable | 21 | The item cannot be stacked, so amount-based operations are invalid. |
| GameNotFound | 22 | The target game does not exist. |
| GameExists | 23 | The game already exists and cannot be created again with the same identity. |
| SecretInfoNotFound | 24 | The requested secret-info record does not exist. |
| SecretInfoExists | 25 | The secret-info record already exists. |
| ExternalNotLinked | 26 | The requested external identity is not linked to the current account. |
| ExternalLinkedOtherAccount | 27 | The external identity is already linked to a different account. |
| ExternalLinkedOtherValue | 28 | The external provider/value pair conflicts with an existing linked value. |
| MasterPlayerNotFound | 29 | The target master player does not exist. |
| StoreItemNotFound | 30 | The target store item does not exist. |
| BuyerNotFound | 31 | The buyer entity does not exist. |
| CanNotBuyThisStoreItem | 32 | The requested store item cannot be purchased in the current state or by the current buyer. |
| ExceptionWhenValidateReceipt | 33 | An exception occurred while validating a platform receipt. |
| StoreInvalid | 34 | The target store/provider configuration is invalid. |
| ReceiptInvalid | 35 | The provided purchase receipt is invalid. |
| StoreItemRemoved | 36 | The target store item was removed and can no longer be used for purchase flows. |
| DisplayNameUsed | 37 | The requested display name is already in use. |
| PlayerBan | 38 | The target player is currently banned. |
| MatchmakingTicketNotFound | 39 | The target matchmaking ticket does not exist. |
| MatchmakingTicketAlreadyCompleted | 40 | The matchmaking ticket already completed and cannot be joined or modified further. |
| MatchmakingPlayerNotJoinedTicket | 41 | The player is not a member of the referenced matchmaking ticket. |
| MatchNotFound | 42 | The requested match does not exist. |
| MatchmakingPlayerJoinedOtherTicket | 43 | The player already joined a different matchmaking ticket that conflicts with this request. |
| MatchmakingQueueNotFound | 44 | The referenced matchmaking queue does not exist. |
| TicketSizeError | 45 | The requested ticket size violates queue configuration. |
| ExecuteError | 46 | CloudScript execution failed inside the target function. |
| VersionInvalid | 47 | The requested CloudScript version is invalid or unavailable. |
| EmailInvalid | 48 | The provided email address is syntactically or semantically invalid. |
| StoreItemPurchasedAndNonConsumable | 49 | The buyer already owns this non-consumable store item. |
| StoreItemExists | 50 | The store item already exists and cannot be created again with the same identity. |
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 | The backend rejected the member but did not map it to a more specific validation category. |
| DataRequired | 2 | The member is required but missing. |
| TypeInvalid | 3 | The member type does not match the expected runtime type. |
| StringNull | 4 | A required string member is null or empty when null is not allowed. |
| StringMinLength | 5 | A string member is shorter than the configured minimum length. |
| StringMaxLength | 6 | A string member is longer than the configured maximum length. |
| NumberMinValue | 7 | A numeric member is lower than the configured minimum value. |
| NumberMaxValue | 8 | A numeric member is higher than the configured maximum value. |
| NumberMustInt | 9 | A numeric member must be an integer but received a non-integer value. |
| GNHashtableNull | 10 | A required `GNHashtable` member is null. |
| GNHashtableMinLength | 11 | A `GNHashtable` member contains fewer entries than allowed. |
| GNHashtableMaxLength | 12 | A `GNHashtable` member contains more entries than allowed. |
| GNArrayNull | 13 | A required `GNArray` member is null. |
| GNArrayMinLength | 14 | A `GNArray` member contains fewer items than allowed. |
| GNArrayMaxLength | 15 | A `GNArray` member contains more items than 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 |
| UpdateTsLastLogin | updateTsLastLogin |
| 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 |