Profanity Detection

Scans user-generated text for profanity and abuse and returns a risk score and a safe/unsafe verdict.

Overview#

scoring/profanity analyzes the string you pass in text and returns isSafe, a riskScore, totalBadWords, the original text and isML, which tells you whether the machine-learning model took part in the decision. Two optional switches shape the output: scoreOnly=yes returns just the score and the verdict, and listBadWords=yes adds the list of offending words.

When to use it#

• Moderate comments, reviews, chat messages and support tickets before they are published.
• Screen usernames, display names and bios at registration.
• Collect a moderation signal to decide between auto-publish, hold for review and reject.

Reading the result#

• isSafe is the quick answer. When it is false, hold or reject the content.
• riskScore is a continuous measure. Scores close to 0 are clean; the higher the value, the more confident the detection. Gurdx raises an event at 0.5 and above, which is a good default threshold for "needs review". Raise it for stricter handling, and lower it for communities with strict rules such as children's apps.
• totalBadWords counts matched terms, and the list from listBadWords is useful for highlighting them to moderators. Do not show the list to the author, as it helps people work around the filter.
• Context matters: words that are offensive in one setting are harmless in another, so use the score as an input to your moderation flow, not as the whole flow.

Notes#

• Counts as one request. Test mode returns fake data, is free and raises no events.
• Included in every plan, including Standard.
• No custom rules are defined for this method. Text is not blacklisted, and it is only stored to the extent needed for data-deletion requests (see User Data Deletion).
• A profanity event is raised when the risk reaches 0.5 and is sent to your webhooks.
• Empty text, or text longer than 10,000 characters, returns error 129 (invalid_text) with HTTP 200.

Request#

• Authenticate with the key parameter or an Authorization: Bearer header.
• Counts as 1 request.
• Available on: Free trial Standard Premium Pay-as-you-go

Parameters#

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/scoring/profanity" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "text=Hello world"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/scoring/profanity?'.http_build_query(['key' => 'YOUR_API_KEY', 'text' => 'Hello world']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","text":"Hello world"});
const res = await fetch(`https://gurdx.cretip.com/api/scoring/profanity?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/scoring/profanity", params={"key": "YOUR_API_KEY", "text": "Hello world"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "data": {
        "isML": true,
        "text": "This is just a normal text",
        "totalBadWords": null,
        "riskScore": 0,
        "isSafe": true,
        "status": "success",
        "executionTime": 120
    }
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

Response fields#