Overview
Return a list of groups that share a specific tag.
Client
Require permission rules group.getGroupsWithTag.selfEnable. See PermissionRules
HTTP
POST /api/rJson/group/client/getGroupsWithTag
Request Headers
| Name | Required | Description |
|---|---|---|
| Auth-Token | true | 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 | true | The SecretKey in SecretInfo with role must is Player. |
| Game-Id | Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting. | |
| Content-Type | true | application/json |
Request Body
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key parameter. (2 - 32 characters) |
| value | string | true | The segment or tag value to be assigned to the group. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | InfoRequestParam parameter. See InfoRequestParam |
| skip | number int | Skip parameter. (from 0) (Default: 0) | |
| limit | number int | Limit parameter. (from 1 to 100) (Default: 10) |
Server
Require permission rules group.getGroupsWithTag.serverSelfEnable. See PermissionRules
HTTP
POST /api/rJson/group/server/getGroupsWithTag
Request Headers
| Name | Required | Description |
|---|---|---|
| Secret-Key | true | The SecretKey in SecretInfo with role must is Server. |
| Game-Id | Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting. | |
| Content-Type | true | application/json |
Request Body
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key parameter. (2 - 32 characters) |
| value | string | true | The segment or tag value to be assigned to the group. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | InfoRequestParam parameter. See InfoRequestParam |
| skip | number int | Skip parameter. (from 0) (Default: 0) | |
| limit | number int | Limit parameter. (from 1 to 100) (Default: 10) |
Admin
Require permission rules group.getGroupsWithTag.adminSelfEnable. See PermissionRules
HTTP
POST /api/rJson/group/admin/getGroupsWithTag
Request Headers
| Name | Required | Description |
|---|---|---|
| Secret-Key | true | The SecretKey in SecretInfo with role must is Admin. |
| Game-Id | Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting. | |
| Content-Type | true | application/json |
Request Body
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key parameter. (2 - 32 characters) |
| value | string | true | The segment or tag value to be assigned to the group. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | InfoRequestParam parameter. See InfoRequestParam |
| skip | number int | Skip parameter. (from 0) (Default: 0) | |
| limit | number int | Limit parameter. (from 1 to 100) (Default: 10) |
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 | |
| results | GroupWithGroupIdResponseData[] | true | Results field in GroupsWithGroupIdResponseData. See GroupWithGroupIdResponseData |
InfoRequestParam
Flags to specify which optional fields should be included in the group response.
| Code | Type | Required | Description |
|---|---|---|---|
| catalogId | boolean | CatalogId field in InfoRequestParam. (Default: false) | |
| members | boolean | Members field in InfoRequestParam. (Default: false) | |
| removeStatus | boolean | RemoveStatus field in InfoRequestParam. (Default: false) | |
| segments | boolean | Include group segments in the response. (Default: false) | |
| customDatas | boolean | Include custom key-value data in the response. (Default: false) | |
| displayName | boolean | Include the group’s display name in the response. (Default: false) | |
| avatar | boolean | Include the group’s avatar reference or URL. (Default: false) | |
| tsCreate | boolean | Include the timestamp of group creation. (Default: false) | |
| tags | boolean | Include tags assigned to the group. (Default: false) | |
| groupCurrencies | boolean | Include current virtual currency balances of the group. (Default: false) | |
| groupStatistics | boolean | Include statistics stored on the group profile. (Default: false) | |
| groupDatas | boolean | GroupDatas field in InfoRequestParam. (Default: false) | |
| groupInventories | boolean | GroupInventories field in InfoRequestParam. (Default: false) | |
| groupDataKeys | string[] | GroupDataKeys field in InfoRequestParam. | |
| groupCurrencyKeys | string[] | GroupCurrencyKeys field in InfoRequestParam. | |
| groupStatisticsKeys | string[] | GroupStatisticsKeys field in InfoRequestParam. | |
| customDataKeys | string[] | CustomDataKeys field in InfoRequestParam. | |
| tagKeys | string[] | TagKeys field in InfoRequestParam. | |
| itemCatalogIds | string[] | ItemCatalogIds field in InfoRequestParam. |
GroupWithGroupIdResponseData
Group profile data resolved using a GroupId query.
| Code | Type | Required | Description |
|---|---|---|---|
| groupId | string | true | Unique identifier for the group. |
| infoResponseParameters | InfoResponseParameters | true | InfoResponseParameters field in GroupWithGroupIdResponseData. See InfoResponseParameters |
InfoResponseParameters
Contains optional metadata fields returned in group data responses.
| Code | Type | Required | Description |
|---|---|---|---|
| catalogId | string | CatalogId field in InfoResponseParameters. | |
| members | GenericModels.MemberItem[] | Members field in InfoResponseParameters. See GenericModels.MemberItem | |
| removeStatus | GenericModels.RemoveStatusItem | RemoveStatus field in InfoResponseParameters. See GenericModels.RemoveStatusItem | |
| segments | string[] | Include group segments in the response. | |
| customDatas | GenericModels.DataItem[] | Include custom key-value data in the response. See GenericModels.DataItem | |
| displayName | string | Include the group’s display name in the response. | |
| avatar | GenericModels.AvatarItem | Include the group’s avatar reference or URL. See GenericModels.AvatarItem | |
| tsCreate | number | Include the timestamp of group creation. | |
| tags | GenericModels.TagItem[] | Include tags assigned to the group. See GenericModels.TagItem | |
| groupDatas | GenericModels.DataItem[] | GroupDatas field in InfoResponseParameters. See GenericModels.DataItem | |
| groupCurrencies | GenericModels.CurrencyItem[] | Include current virtual currency balances of the group. See GenericModels.CurrencyItem | |
| groupStatistics | GenericModels.StatisticsItem[] | Include statistics stored on the group profile. See GenericModels.StatisticsItem | |
| groupInventories | GenericModels.InventoryItem[] | GroupInventories field in InfoResponseParameters. See GenericModels.InventoryItem |
Generic.MemberItem
Information about a member within a group, including role and status.
| Code | Type | Required | Description |
|---|---|---|---|
| memberId | string | true | MemberId field in MemberItem. |
| status | number | true | Current state or flag representing the object’s availability. |
Generic.RemoveStatusItem
Represents the removal state and related metadata for an entity.
| Code | Type | Required | Description |
|---|---|---|---|
| tsRemove | number | true | TsRemove field in RemoveStatusItem. |
| reason | string | Text explaining why the ban or action was applied. |
Generic.DataItem
Represents a structured key-value data pair stored in a player or group profile.
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key used in a structured data pair. |
| value | any | true | Value assigned to the specified key. |
Generic.AvatarItem
Represents avatar-related metadata such as image, icon, and background colors.
| Code | Type | Required | Description |
|---|---|---|---|
| type | number | true | Type field in AvatarItem. |
| value | string | true | Value assigned to the specified key. |
Generic.TagItem
Represents a tag or category label used for filtering or grouping entities.
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key used in a structured data pair. |
| value | string | true | Value assigned to the specified key. |
Generic.CurrencyItem
Defines a virtual currency identifier and its current amount.
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key used in a structured data pair. |
| value | number | true | Value assigned to the specified key. |
Generic.StatisticsItem
Represents a named statistic and its numeric value.
| Code | Type | Required | Description |
|---|---|---|---|
| key | string | true | Key used in a structured data pair. |
| value | number | true | Value assigned to the specified key. |
Generic.InventoryItem
Summarizes the inventory contents and counts for a player or group.
| Code | Type | Required | Description |
|---|---|---|---|
| itemId | string | true | ItemId field in InventoryItem. |
| catalogId | string | true | CatalogId field in InventoryItem. |
| classId | string | true | ClassId field in InventoryItem. |
ErrorCode
| Name | Code |
|---|---|
| Ok | 1 |
| KeyNotFound | 9 |
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. |