> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-usernames.md). # API Docs: Usernames ## **Introduction** GGWP provides an API you can use for processing username data and integrating actions in your application workflow. This product is designed to identify various types of toxic content associated with usernames, including similar use cases like team and guild names, both at creation time as well as over time as users make changes or new social trends emerge shaping the notion of what’s considered toxic. ## Onboarding Guide Before starting to use the API, it is important to understand how this product works in order to unlock its full potential. ### **Understanding GGWP’s Username Moderation Solution** The main use case for this product is to prevent the formation of toxic usernames and team names that can be offensive to other community members. In addition, this tool can be used to surface existing usernames that might become toxic over time, as well as to validate and triage reports filed from users flagging another user's username. You will make 1 API call for each individual username, including a unique identifier to track the sender (more info in the “Username API” section below). GGWP takes care of processing this information and providing relevant insights associated with that username and the user behind it. Once the response is sent back to you, we recommend integrating different actions to improve the user experience on your platform. Some example actions could be prompting a new user to choose a different username or notifying an existing user that they should make a change to their profile name. ### **Configurable Settings** Custom settings can be defined in order to select the types of content you want to prevent in usernames across your platform. This can be done in 2 ways: * At onboarding time (preferable) - you share the necessary configurations with your Account Manager and GGWP incorporates them in your specific API settings. * During each API call - through the use of headers, you can also input some custom settings every time you make an API call (see “Username API” section for details). This has some limitations since not all custom elements can be provided, and is more prone to error. Here is a list of things that can be configured: * **Topics**: Available topics include Violence, Sexual Content, Verbal Abuse, Identity Hate, Profanity, Link Sharing, Drugs and Self-Harm. * **Filter Strength**: Filter strength configurations in the Username API are based on a parent lens of safety. There are typically 4 values that can be selected for each topic, with a few exceptions. These 4 values are: * Filter strength = “Off” - the filter is not active, so all forms of toxicity are allowed. Suitable for environments with adults where we don’t want to impose any restrictions. * Filter strength = “Low” - only filters extremely offensive content, but allows for moderate and low forms of toxicity to go through. Suitable for environments with adults only. * Filter strength = “Medium” - filters out extreme and moderate forms of toxicity, only letting through mild toxicity. Suitable for environments with teenagers where some innocuous toxicity can be tolerated. * Filter strength = “High” - filters out all forms of toxicity. Suitable for environments with presence of kids. * **Custom Content:** If you have a custom allowlist or blocklist with terms you would like to treat differently, we can also incorporate them into your specific API settings. This can be useful, for example, if there are certain character names you want to reserve and prevent people from using in their profiles. ### **Processing Modes** To support different performance requirements, the Username API offers two processing modes. Both use the same categories and configurable settings but differ in latency and analytical depth. **Quality Mode (default)** Runs GGWP’s full model for maximum detection accuracy and broader linguistic generalization. * **Latency:** \~500–700 ms median. * **Language Coverage:** Supports a significantly larger set of languages. * **Best For:** Communities with stricter safety policies or younger audiences where it is important to minimize the risk of harmful usernames slipping through moderation. Also useful for offline checks where latency is less critical, such as report validation or periodic audits of existing usernames. **Performance Mode** Uses a streamlined model optimized for low latency while still covering the core languages supported by the Username API. * **Latency:** \~100–150 ms median * **Language Coverage:** Supports the standard language set described in the Language Support section * **Best For:** Real-time username validation and high-volume workflows where fast response times are required. ### **Language Support** The GGWP Username API currently supports the following languages: Arabic, Chinese, English, French, German, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish and Turkish. In addition: * **Quality Mode** extends language coverage to **100+ languages**, thanks to its more diverse underlying training dataset. * **Performance Mode** is optimized for the standard language set listed above. If you require support for additional languages, please contact your Account Manager to review availability or upcoming roadmap items. ## Authentication GGWP uses API keys to grant authorized users secure access to all of the API endpoints listed below. All requests must supply the following HTTP header along with the API key provisioned: `x-api-key: ` Each API key: * Uniquely identifies your platform/game * Gives API access to all APIs listed in this document * Has a specific rate limit on the number of requests that can be made per second as well as a possible set quota of the number of requests that can be made on a month to month basis * Should be kept a secret and should not be shared with any unauthorized games / users * Once lost, a new key will have to be regenerated Please contact your GGWP Account Manager for provisioning an API key as well as setting the correct rate limits required for your game. ## How to use your API key The following is an example invocation of the production API endpoint using a valid API key (key is redacted in this example): ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \ --header 'x-api-key: api_key' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` An invalid API key will return a `403` return code. Below is an example response with an invalid API key: ```bash < HTTP/2 403 < date: Thu, 18 Nov 2021 21:28:27 GMT < content-type: application/json < content-length: 23 < x-amzn-requestid: f4361ec6-71bc-478f-98cd-da0fe9df829b < x-amzn-errortype: ForbiddenException < x-amz-apigw-id: JBPLRHGjPHcFdbg= < * Connection #0 to host api.ggwp.com left intact {"message":"Forbidden"}* Closing connection 0 ``` ## Username API \[ Base URL: `api.ggwp.com`] `POST` /username/v1/validate ### **Description** This API endpoint will process an input username and user id, along with a list of configurable options on toxicity filtering strengths, and return information at 2 levels: * Username Details - indicators for the presence and severity of toxic content in the username, as well as the confidence of such indicators if toxicity is found. * User Details - contextual information associated to that particular user based on the history of calls to the username API, including recently blocked attempts. This enables you to trigger different actions for repeat offenders. ### **Headers** Configuration settings can be provided either through your GGWP account setup (recommended) or dynamically on each request using HTTP headers.
HeaderRequiredDescription
x-api-keyYesYour GGWP API key used for authentication.
Content-TypeYesMust be set to application/json.
x-api-configOptionalBase64-encoded JSON object with per-request configuration overrides (topics, filter strengths). See below for more details. If not provided, default or onboarding-time settings apply.
x-api-processing-modeOptionalSelects the processing mode for the request. Accepted values: quality (default) or performance.
**Configurable Topics (via `x-api-config`)** Below are the configurable topics and their supported filter strength values. These values are provided inside the JSON passed through `x-api-config`: * **violence**: Flag language that encourages, glorifies, or threatens physical harm or destruction towards individuals or groups. This includes threats, death wishes, and references to violent acts. Supported filter strength values are: * off: This filter is turned off * low: Flags extreme and graphic violent references only * Examples: "getcancer", "hopeyoudie", "rapist" * medium: In addition to the instances captured above, this will flag mentions to other violent acts not suitable for teenage or kid audiences * Examples: "genocide", "lynch", "slaughter", "torture", "kidnapper" * high: In addition to the instances captured above, this will also flag mild violent references * Examples: "kill", "death", "shooter", "sniper", "blood", "murder" * **sexual\_content**: Flag language containing explicit sexual comments, innuendos, or references that are inappropriate or offensive. This includes depictions of nudity, mentions to sexual acts, or sexually suggestive language. Supported filter strength values are: * off: This filter is turned off * low: Flags extreme references to sexual violence * Examples: "childmolester", "daterape", "gatorbait", "sexoffender" * medium: In addition to the instances captured above, this will flag other mentions to sexual acts and any moderately graphic sexual language * Examples: "suckmydick", "penisfucker", "pussy", "blowjob", "gangbang" * high: In addition to the instances captured above, this will also flag mild sexual references seen as inappropriate for children * Examples: "boobs", "cock", "porn", "sexy", "butt" * **verbal\_abuse**: Flag usernames that contain insults, personal attacks, derogatory remarks or other targeted offensive language. Supported filter strength values are: * off: This filter is turned off * low: Flags highly offensive and insulting terms only * Examples: "fuktard", "schizo", "mong", "assmonkey" * medium: In addition to the instances captured above, this will flag other forms of abusive language or directed insults * Examples: "bastard", "douche", "asshole", "shitfucker", "bitch" * high: In addition to the instances captured above, this will also flag mildly offensive terms, and is most appropriate for younger audiences * Examples: "dummy", "idiot", "incel", "braindead", "smartass" * **identity\_hate**: Flag usernames containing discriminatory language towards any person or group based on religion, ethnicity, nationality, race, gender, sexual orientation or other identity factors. Supported filter strength values are: * off: This filter is turned off * medium: Filters out extreme hateful slurs only * Examples: "nigger", "faggot", "cunt", "retard", "chink", "tranny", "slut" * high: In addition to the instances captured above, this will also flag identity terms that are frequently associated with more subtle biases towards a specific identity group * Examples: "gay", "homo", "queer", "nazi", "lesbian" * **profanity**: Flag usernames that include obscene or vulgar language, or swear words. Supported filter strength values are: * off: This filter is turned off * medium: Flags more obscene forms of profanity and offensive swear words * Examples: "fuck", "stfu", "motherfucking", "scumbag" * high: In addition to the instances captured above, this will also flag mild profanity * Examples: "shit", "dammit", "ugly", "stupid", "noob", "wtf", "piss" * **link\_sharing**: Flag usernames that contain external links to prevent users from sharing inappropriate websites, ads, scams, or other potentially harmful content. Supported filter strength values are: * off: This filter is turned off * medium: Flag URLs known to be associated with common inappropriate or mature content (e.g. sexual content; gambling and other illegal activity; likely phishing attacks) * high: Flags all URLs * **drugs**: Flag usernames that contain references to illegal substances, drug use, or drug culture that are inappropriate for the gaming environment. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will flag all drug references * Examples: "overdose", "drunk", "crack", "alcohol", "stoned", "cocaine" * **self\_harm**: Flag usernames that encourage, glorify, or suggest self-injury, suicide, or other forms of self-destructive behavior. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will block promoting harmful behaviors * Examples: "kys", "suicide", "cutyourself", "endurlife" * **politics:** Flag usernames that contain political references, such as political parties, politicians, or political movements. Supported filter values are: * off: This filter is turned off * on: This filter is turned on * Examples: "obama", "trump", "liberal", "BLM", "socialist" * **religion:** Flag usernames that contain religious references, such as religions, religious figures, or items and locations commonly associated with religion. Supported filter values are: * off: This filter is turned off * on: This filter is turned on * Examples: "catholic", "buddha", "faith", "pope", "prophet", "jewish" * **ideologies:** Flag usernames that contain references to harmful ideologies. Supported filter values are: * off: This filter is turned off * on: This filter is turned on * Examples: "zionism", "supremacy", "caste", "antivax", "kkk", "misogyny" * **controversial:** Flag usernames that contain references to controversial figures, events, or groups. Supported filter values are: * off: This filter is turned off * on: This filter is turned on * Examples: "hitler", "jeffreydahmer", "hamas", "covid19", "slavery" **Passing Configurations** 1. Sample JSON (`config.json`) ```json { "violence": "off", "sexual_content": "low", "verbal_abuse": "medium", "identity_hate": "medium", "profanity": "high", "link_sharing": "high", "drugs": "off", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` 2. Base64-encode the JSON ```bash base64 config.json ``` 3. Sample encoded output 
ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=
4. Example curl request 
curl --request POST 'https://api.ggwp.com/username/v1/validate' \
     --header 'x-api-key:<API_KEY>' \
     --header 'Content-Type: application/json' \
     --header 'x-api-config: ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=' \
     --header 'x-api-processing-mode: performance' \
     --data-raw '{
       "username": "fuckyou123", 
       "user_id": "user001", 
       "timestamp": "2022-01-25 09:44:12"
     }'
**Default Configurations** If the `x-api-config` header is NOT provided: ```json { "violence": "high", "sexual_content": "high", "verbal_abuse": "high", "identity_hate": "high", "profanity": "high", "link_sharing": "high", "drugs": "on", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` If `x-api-processing-mode` is not provided: ```json { "processing_mode": "quality" } ``` ### **Parameters** `body`: Dictionary containing the following fields:\ (*Needs to be in utf-8 encoding)* * **username:** String with the username to be validated. * **user\_id:** Unique identifier for the user who submitted the username. If this is a new user for which a *user\_id* hasn’t been created yet, we recommend that you use the format described below, where *sessionID* can be based on any activity that identifies that user, like browser navigation settings, for example. ```json user_id = "anonymous_sessionID" ``` * (OPTIONAL) **timestamp:** Time the username was created in *YYYY-MM-DD HH:MM:SS* format, in UTC. If not added, then server side UTC timestamp is added in its place. Example ```json { "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" } ``` Sample call: ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \ --header 'x-api-key: api_key' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` ### **Output** #### 200 response Returns a JSON object with the following top-level fields:
username_details Username-level moderation results for the submitted username. * `username` — The username that was submitted for moderation. * `flag` — `true` if the username was flagged by any configured moderation category or custom rule. * `severity` — Overall severity assigned to the username. Possible values: `none`, `low`, `medium`, `high`, and `custom`. * `custom` is used when GGWP does not flag the username, but the username matches a term from the client custom blocklist. * `confidence` — Confidence level for the overall username-level detection. Possible values: `none`, `low`, `medium`, or `high`. This can be used to tune moderation behavior: * To reduce false positives, exclude `low` confidence detections from automatic enforcement. * To catch more potentially harmful usernames, include `low` confidence detections, with the tradeoff that more borderline usernames may be flagged. Category fields indicate which moderation categories were detected for the username. These fields are booleans and are not mutually exclusive. A username may be flagged for more than one category. * `politics` — `true` if the username matched political content signals. * `controversial` — `true` if the username matched controversial content signals. * `sexual_content` — `true` if the username matched sexual content signals. * `violence` — `true` if the username matched violence-related signals. * `profanity` — `true` if the username matched profanity signals. * `link` — `true` if the username appears to contain a URL, domain, or link-like content. * `self_harm` — `true` if the username matched self-harm-related signals. * `custom` — `true` if the username matched a client custom blocklist term. * `religion` — `true` if the username matched religion-related content signals. * `identity_hate` — `true` if the username matched identity-based hate signals. * `drugs` — `true` if the username matched drug-related content signals. * `verbal_abuse` — `true` if the username matched insults, or abusive language signals. * `ideologies` — `true` if the username matched ideology-related content signals.
user_details User-level username moderation history for the submitted `user_id`. This object helps identify repeated username abuse within a short time window, rather than only evaluating the current username in isolation. * `user_id` — The user identifier provided in the request. * `recent_username_calls` — Number of username moderation requests associated with this user in the last 5 minutes. * `recent_flagged` — Number of username moderation requests associated with this user that were flagged in the last 5 minutes. * `recent_flagged_usernames` — List of usernames associated with this user that were flagged in the last 5 minutes.
Example response: ```json { "username_details": { "username": "fuckoff", "flag": true, "severity": "medium", "confidence": "high", "politics": false, "controversial": false, "sexual_content": false, "violence": false, "profanity": true, "link": false, "self_harm": false, "custom": false, "religion": false, "identity_hate": false, "drugs": false, "verbal_abuse": true, "ideologies": false }, "user_details": { "user_id": "123", "recent_username_calls": 8, "recent_flagged": 7, "recent_flagged_usernames": [ "yousuck", "yousuck", "fuckyou123", "fuckyouoff", "fuckyou123" ] } } ``` #### 400 response Returned when the request is invalid. Common causes include: * Invalid JSON input * Missing required fields * Invalid field types * Malformed request body #### 403 response Returned when the API key is missing, invalid, or does not have access to this endpoint. #### 500 response Returned when the request could not be completed due to an internal server error.