Text Moderation

Analyze text for potential moderation issues.

POSThttps://api.safecomms.dev/moderation/text

The text moderation endpoint analyzes a string of text for various types of unsafe content, including hate speech, harassment, self-harm, sexual content, and violence. It can also detect Personally Identifiable Information (PII) and automatically redact sensitive or offensive content.

Request Parameters

Parameter	Type	Description
content	string	The text content to analyze. Maximum length depends on your subscription tier.
language	string	ISO 639-1 language code (e.g., 'en', 'es'). Note: Set to `'auto'` for automatic language detection (Business and Enterprise tiers only).
replace	boolean	If true, returns `moderatedContent` with flagged terms replaced by asterisks. Default: `false`.
pii	boolean	If true, scans for Personally Identifiable Information (emails, phone numbers, etc.). Default: `false`.
replaceSeverity	string	Minimum severity level to trigger replacement. Options: 'Low', 'Medium', 'High'.
moderationProfileId	string	The ID of a custom moderation profile to apply specific rules.

Token Usage & Costs

Text moderation uses a base cost of 1 token per request. Additional features (add-ons) may incur extra token costs.

Feature	Cost	Tier	Condition
Base Request	1 Token	Free+	Always applied.
Non-English Language	+1	Pro+	Applied when `language` is not 'en'. If set to 'auto' and resolves to English, no surcharge is applied.
Text Replacement	+1	Starter+	Applied when `replace` is set to `true`.
PII Detection	+1	Starter+	Applied when `pii` is set to `true`.

* Note: You must have enough tokens in your balance to cover the maximum potential cost of the request (Base + all enabled add-ons) to initiate the call.

Example Request

{
  "content": "This is some text to check.",
  "language": "en",
  "replace": true,
  "pii": false
}

Response Object

The API returns a JSON object containing the analysis results.

isClean: Boolean indicating if the content passed all checks.
issues: List of specific issues found in the content.
safeContent: The content with offensive parts redacted (if replacement was enabled).

{
  "id": "req_123456789",
  "isClean": false,
  "severity": "High",
  "issues": [
    {
      "term": "offensive term",
      "context": "usage context",
      "category": "Hate",
      "severity": "High"
    }
  ],
  "categoryScores": {
    "Hate": "High"
  },
  "safeContent": "This is some **** to check.",
  "isBypassAttempt": false,
  "uncategorizedHarm": false
}

POSThttps://api.safecomms.dev/moderation/text/batch

Process multiple text moderation requests in parallel. This endpoint allows you to submit up to 100 text items (depending on your tier) and receive all results in a single response. All items are processed concurrently for optimal performance.

Request Parameters

Parameter	Type	Description
items	array	Array of text items to moderate. Each item must have `id` and `content` properties. Batch Size Limits: Free: 5 items Basic: 25 items Starter: 50 items Pro+: 100 items
language	string	Language code applied to all items (e.g., 'en', 'es').
replace	boolean	If true, returns moderated content for all items. Default: `false`.
pii	boolean	If true, scans all items for PII. Default: `false`.
replaceSeverity	string	Minimum severity level to trigger replacement for all items.
moderationProfileId	string	Custom moderation profile ID applied to all items.

Example Request

{
  "items": [
    {
      "id": "msg1",
      "content": "First message to check"
    },
    {
      "id": "msg2",
      "content": "Second message to check"
    }
  ],
  "language": "en",
  "replace": true,
  "pii": false
}

Response Object

The API returns an object with a results array. Each result contains the item ID and either the moderation result or an error message.

{
  "results": [
    {
      "id": "msg1",
      "result": {
        "id": "req_123456789",
        "isClean": true,
        "severity": "None",
        "issues": [],
        "categoryScores": {}
      },
      "error": null
    },
    {
      "id": "msg2",
      "result": {
        "id": "req_987654321",
        "isClean": false,
        "severity": "High",
        "issues": [
          {
            "term": "offensive term",
            "context": "usage context",
            "category": "Hate",
            "severity": "High"
          }
        ]
      },
      "error": null
    }
  ]
}

Important Notes

Rate Limiting: Each item in the batch consumes one rate limit permit. Batch size is limited to 50% of your tier's rate limit to prevent exhaustion.
Independent Processing: Each item is processed independently. If one item fails, others will still complete successfully.
Parallel Execution: All items are processed concurrently, making batch requests much faster than sequential single requests.
Token Usage: Each item in the batch consumes tokens based on the same pricing as single requests (base + add-ons).