Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

You can create API keys in the API Keys section of your account.

Primary Endpoint: Content Moderation

POST /api/moderate

Submit text for content moderation analysis with optional custom metadata tracking.

Request Body

{
  "text": "Your text to moderate here",
  "id": "optional-request-id",
  "custom_field_1": "optional-username",
  "custom_field_2": "optional-user-id",
  "custom_field_3": "optional-session-id",
  "custom_field_4": "optional-device-info",
  "custom_field_5": "optional-metadata"
}

Custom Fields: Up to 5 custom fields (255 chars each) can be sent with each request. These are stored with the request and searchable in your activity history. Use them to track usernames, IDs, sessions, or any application-specific metadata.

Response

{
  "profanity_detected": true,
  "normalized_terms": ["profanity1", "profanity2"],
  "censor_spans": [
    {
      "start": 10,
      "end": 15,
      "term": "profanity1",
      "matched_text": "pr0f4n1ty",
      "detector": "obfuscated",
      "confidence": 0.9
    }
  ],
  "censored_text": "Your text ******** here",
  "detections": [
    {
      "detector": "exact_blacklist",
      "confidence": 1.0,
      "matched_terms": ["profanity1"],
      "span_count": 1
    },
    {
      "detector": "obfuscated",
      "confidence": 0.9,
      "matched_terms": ["profanity2"],
      "span_count": 1
    }
  ],
  "model_succeeded": true,
  "usage": {
    "hourly_used": 10,
    "hourly_limit": 10,
    "daily_used": 45,
    "daily_limit": 120
  }
}

Detection Layers

Our moderation system uses multiple detection layers:

• Exact Blacklist: Direct word matching with word boundaries (confidence: 1.0)
• Obfuscated: Detects leet speak, homoglyphs, and character substitutions (confidence: 0.9)
• Fuzzy: Catches creative misspellings using Levenshtein distance (confidence: 0.75)

Categories detected: Profanity, Slurs, Violence, Sexual Content, Drugs, Extremism

Rate Limits

Free Plan:

• 10 requests per hour
• 120 requests per day
• Access to basic analytics (7 days)

Pro Plan ($9.99/month):

• Unlimited requests
• Advanced analytics (30 days)
• Detection pattern insights
• Priority support

Activity & Analytics Endpoints

GET /api/activity

Retrieve paginated list of your API requests with search and filtering.

Query Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 50, max: 100)
• search - Search across text and custom fields
• filter_type - Filter by 'detected', 'clean', or null for all
• sort_by - Sort field (default: 'timestamp')
• sort_order - 'asc' or 'desc' (default: 'desc')

GET /api/activity/{request_id}

Get detailed information for a specific request including all custom fields.

GET /api/insights

Get analytics and insights about your API usage, detection rates, and patterns.

Example: Python with Custom Fields

import requests

url = "https://moderation.apforged.com/api/moderate"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "text": "Check this text for profanity",
    "custom_field_1": "john_doe",      # Username
    "custom_field_2": "12345",          # User ID
    "custom_field_3": "session_abc",    # Session ID
    "custom_field_4": "iOS",            # Platform
    "custom_field_5": "v2.1.0"          # App version
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result['profanity_detected']:
    print(f"⚠️ Profanity detected: {result['normalized_terms']}")
    print(f"Censored: {result['censored_text']}")
else:
    print("✅ Content is clean")

print(f"Usage: {result['usage']['hourly_used']}/{result['usage']['hourly_limit']}")

Example: JavaScript/Node.js

const axios = require('axios');

const url = 'https://moderation.apforged.com/api/moderate';
const headers = {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
};
const data = {
    text: 'Check this text for profanity',
    custom_field_1: 'john_doe',      // Username
    custom_field_2: '12345',          // User ID
    custom_field_3: 'session_abc',    // Session ID
    custom_field_4: 'iOS',            // Platform
    custom_field_5: 'v2.1.0'          // App version
};

axios.post(url, data, { headers })
    .then(response => {
        const result = response.data;
        if (result.profanity_detected) {
            console.log('⚠️ Profanity detected:', result.normalized_terms);
            console.log('Censored:', result.censored_text);
        } else {
            console.log('✅ Content is clean');
        }
        console.log(`Usage: ${result.usage.hourly_used}/${result.usage.hourly_limit}`);
    })
    .catch(error => {
        if (error.response?.status === 429) {
            console.error('Rate limit exceeded:', error.response.data);
        } else {
            console.error('Error:', error.response?.data);
        }
    });

Example: cURL

curl -X POST https://moderation.apforged.com/api/moderate \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "text": "Check this text for profanity",
    "custom_field_1": "john_doe",
    "custom_field_2": "12345"
  }'

Example: Unity C#

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.Text;

public class ModerationAPI : MonoBehaviour
{
    private const string API_URL = "https://moderation.apforged.com/api/moderate";
    private const string API_KEY = "your_api_key_here";

    [System.Serializable]
    public class ModerationRequest
    {
        public string text;
        public string custom_field_1;
        public string custom_field_2;
        public string custom_field_3;
    }

    [System.Serializable]
    public class ModerationResponse
    {
        public bool profanity_detected;
        public string[] normalized_terms;
        public string censored_text;
    }

    public IEnumerator ModerateText(string chatMessage, string username, string userId)
    {
        // Create request
        var request = new ModerationRequest
        {
            text = chatMessage,
            custom_field_1 = username,
            custom_field_2 = userId,
            custom_field_3 = "Unity-Game"
        };

        string jsonData = JsonUtility.ToJson(request);
        byte[] bodyRaw = Encoding.UTF8.GetBytes(jsonData);

        // Create web request
        using (UnityWebRequest webRequest = new UnityWebRequest(API_URL, "POST"))
        {
            webRequest.uploadHandler = new UploadHandlerRaw(bodyRaw);
            webRequest.downloadHandler = new DownloadHandlerBuffer();
            webRequest.SetRequestHeader("Content-Type", "application/json");
            webRequest.SetRequestHeader("x-api-key", API_KEY);

            // Send request
            yield return webRequest.SendWebRequest();

            if (webRequest.result == UnityWebRequest.Result.Success)
            {
                ModerationResponse response = JsonUtility.FromJson<ModerationResponse>(
                    webRequest.downloadHandler.text
                );

                if (response.profanity_detected)
                {
                    Debug.LogWarning($"⚠️ Profanity detected from {username}");
                    Debug.Log($"Censored: {response.censored_text}");
                    // Block the message or use censored version
                }
                else
                {
                    Debug.Log($"✅ Clean message from {username}");
                    // Allow the message
                }
            }
            else
            {
                Debug.LogError($"Moderation API Error: {webRequest.error}");
            }
        }
    }

    // Usage example:
    // StartCoroutine(ModerateText("Player message here", "PlayerName", "12345"));
}

Example: Unreal Engine C++

// ModerationService.h
#pragma once

#include "CoreMinimal.h"
#include "Http.h"
#include "Json.h"
#include "JsonUtilities.h"

class YOURGAME_API FModerationService
{
public:
    static void ModerateText(
        const FString& TextToModerate,
        const FString& Username,
        const FString& UserId,
        TFunction<void(bool bProfanityDetected, const FString& CensoredText)> OnComplete
    );

private:
    static void OnResponseReceived(
        FHttpRequestPtr Request,
        FHttpResponsePtr Response,
        bool bWasSuccessful,
        TFunction<void(bool, const FString&)> Callback
    );
};

// ModerationService.cpp
#include "ModerationService.h"

void FModerationService::ModerateText(
    const FString& TextToModerate,
    const FString& Username,
    const FString& UserId,
    TFunction<void(bool, const FString&)> OnComplete)
{
    // Create HTTP request
    TSharedRef<IHttpRequest, ESPMode::ThreadSafe> HttpRequest = 
        FHttpModule::Get().CreateRequest();
    
    HttpRequest->SetURL(TEXT("https://moderation.apforged.com/api/moderate"));
    HttpRequest->SetVerb(TEXT("POST"));
    HttpRequest->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
    HttpRequest->SetHeader(TEXT("x-api-key"), TEXT("your_api_key_here"));
    
    // Create JSON payload
    TSharedPtr<FJsonObject> JsonObject = MakeShareable(new FJsonObject);
    JsonObject->SetStringField(TEXT("text"), TextToModerate);
    JsonObject->SetStringField(TEXT("custom_field_1"), Username);
    JsonObject->SetStringField(TEXT("custom_field_2"), UserId);
    JsonObject->SetStringField(TEXT("custom_field_3"), TEXT("UnrealEngine"));
    
    FString OutputString;
    TSharedRef<TJsonWriter<>> Writer = 
        TJsonWriterFactory<>::Create(&OutputString);
    FJsonSerializer::Serialize(JsonObject.ToSharedRef(), Writer);
    
    HttpRequest->SetContentAsString(OutputString);
    
    // Bind callback
    HttpRequest->OnProcessRequestComplete().BindLambda(
        [OnComplete](FHttpRequestPtr Request, FHttpResponsePtr Response, 
                     bool bWasSuccessful)
        {
            if (bWasSuccessful && Response.IsValid())
            {
                TSharedPtr<FJsonObject> JsonResponse;
                TSharedRef<TJsonReader<>> Reader = 
                    TJsonReaderFactory<>::Create(Response->GetContentAsString());
                
                if (FJsonSerializer::Deserialize(Reader, JsonResponse))
                {
                    bool bProfanityDetected = 
                        JsonResponse->GetBoolField(TEXT("profanity_detected"));
                    FString CensoredText = 
                        JsonResponse->GetStringField(TEXT("censored_text"));
                    
                    if (bProfanityDetected)
                    {
                        UE_LOG(LogTemp, Warning, 
                            TEXT("⚠️ Profanity detected! Censored: %s"), 
                            *CensoredText);
                    }
                    else
                    {
                        UE_LOG(LogTemp, Log, TEXT("✅ Content is clean"));
                    }
                    
                    OnComplete(bProfanityDetected, CensoredText);
                }
            }
            else
            {
                UE_LOG(LogTemp, Error, TEXT("Moderation API request failed"));
                OnComplete(false, TEXT(""));
            }
        }
    );
    
    HttpRequest->ProcessRequest();
}

// Usage example in your game code:
/*
FModerationService::ModerateText(
    PlayerChatMessage,
    PlayerUsername,
    PlayerUserId,
    [](bool bProfanityDetected, const FString& CensoredText)
    {
        if (bProfanityDetected)
        {
            // Use censored version or block message
            DisplayChatMessage(CensoredText);
        }
        else
        {
            // Display original message
            DisplayChatMessage(PlayerChatMessage);
        }
    }
);
*/

Retrieving Activity Data

# Get recent activity with search
curl -X GET "https://moderation.apforged.com/api/activity?search=john_doe&filter_type=detected" \
  -H "Cookie: apforged_session=your_session_token"

# Get specific request details
curl -X GET "https://moderation.apforged.com/api/activity/123" \
  -H "Cookie: apforged_session=your_session_token"

Activity endpoints require browser session authentication. Use the web interface to view and search your request history with full drill-down capabilities.

Custom Fields Best Practices

• Username Tracking: Use custom_field_1 to track which user sent content
• User ID: Store numeric user IDs in custom_field_2 for database correlation
• Session/Context: Track sessions, chat rooms, or conversation IDs
• Platform Info: Store device type, OS, app version for analytics
• Metadata: Any application-specific data you need to track

Note: Custom fields are searchable and visible in your activity dashboard. Don't store sensitive information like passwords or tokens.

Error Codes

• 200 - Success
• 400 - Bad request (empty text or invalid format)
• 401 - Invalid or missing API key
• 404 - Resource not found (for activity endpoints)
• 429 - Rate limit exceeded (includes usage details in response)
• 500 - Server error (contact support if persistent)

Webhooks (Coming Soon)

Subscribe to real-time notifications when content is flagged. Configure webhooks in your account settings to receive POST requests with detection results.

Support & Resources

• Test your API: Use the "Test API" section to validate your integration
• View Analytics: Check the "Insights" section for usage patterns and detection rates
• Activity History: Click on metrics in Insights to drill down into specific requests
• API Keys: Manage multiple keys for different applications or environments

For technical support or feature requests, contact us at [email protected]