POST Content Moderation & Spam API
/api/v1/ai/spam-detection
Analyze text to detect spam, promotional abuse, toxicity, and PII, keeping your platform safe from malicious actors.
Architecture Role & AI Definition
Content Moderation & Spam API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
text |
string | Required | The raw text content to analyze (Max: 5,000 characters). |
content_type |
string | Optional | Context of where the text came from (e.g., "blog_comment", "email", "product_review"). Helps the AI understand the expected format. |
strictness |
string | Optional | Filter strictness: "low", "medium", or "high". Default is "medium". |
detect_toxicity |
boolean | Optional | Optional. Set to true to analyze the text for hate speech, harassment, and severe profanity. |
detect_pii |
boolean | Optional | Optional. Set to true to detect Personal Identifiable Information (emails, phone numbers, SSNs). |
return_sanitized |
boolean | Optional | Optional. Set to true to receive a redacted version of the text where malicious links, profanity, and PII are replaced with "[REMOVED]". |
model |
string | Optional | Optional AI model to use. |
Example Request (Full Moderation)
In this example, we test a highly abusive comment and request all advanced moderation features, including sanitization.
{
"text": "You guys are idiots! Call me at 555-019-2831 or visit my crypto scam site http://bit.ly/scam-link to win free money.",
"content_type": "blog_comment",
"strictness": "high",
"detect_toxicity": true,
"detect_pii": true,
"return_sanitized": true
}curl -X POST https://rsflowhub.com/api/v1/ai/spam-detection \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "You guys are idiots! Call me at 555-019-2831 or visit my crypto scam site http://bit.ly/scam-link to win free money.",
"content_type": "blog_comment",
"strictness": "high",
"detect_toxicity": true,
"detect_pii": true,
"return_sanitized": true
}'Example Response
The API processes the text and returns a comprehensive moderation report, including the safely redacted text.
{
"success": true,
"data": {
"result": {
"is_spam": true,
"spam_score": 0.98,
"spam_category": "promotional",
"reason": "Contains a suspicious shortlink and unsolicited promotional language.",
"is_toxic": true,
"toxicity_score": 0.85,
"contains_pii": true,
"pii_types": ["phone_number"],
"sanitized_text": "You guys are [REMOVED]! Call me at [REMOVED] or visit my crypto scam site [REMOVED] to win free money."
}
},
"meta": {
"credits_used": 2,
"credits_remaining": 991
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/spam-detection' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"text": "You guys are idiots! Call me at 555-019-2831 or visit http://bit.ly/scam-link",
"content_type": "blog_comment",
"detect_toxicity": true,
"detect_pii": true,
"return_sanitized": true
}'Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (2 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |