{% extends "base.html" %} {% block title %}API Documentation - AutoModerate{% endblock %} {% block scripts %} {% endblock %} {% block content %}

API Documentation

Back to Dashboard
Quick Navigation

Overview

The AutoModerate API provides programmatic access to content moderation services. All endpoints require authentication via API keys.

Base URL: {{ request.host_url.rstrip('/') }}/api
Features:
  • Real-time content moderation
  • Custom rule-based filtering
  • AI-powered analysis
  • WebSocket real-time updates
  • Comprehensive response data

Authentication

All API requests require authentication using an API key in the request headers.

Header Format:
X-API-Key: your-api-key-here
Getting Your API Key:
  1. Go to your project dashboard
  2. Navigate to "API Keys" section
  3. Create a new API key
  4. Copy the generated key (starts with am_)
Security: Keep your API key secure and never share it publicly. API keys have full access to your project's moderation capabilities.

API Endpoints

Method Endpoint Description Authentication
POST /api/moderate Moderate content Required
GET /api/health Check API status None
GET /api/docs API documentation None

Content Moderation

Endpoint: POST /api/moderate
Request Body:
{
    "type": "text",
    "content": "Your content to moderate",
    "metadata": {
        "user_id": "user123",
        "source": "web"
    }
}
Parameters:
  • type (string, required): Content type - "text", "image", "video"
  • content (string, required): The content to moderate
  • metadata (object, optional): Additional context about the content
    • user_id (string, optional): External user identifier for tracking. If provided, moderation results and stats will be associated with this user. This enables per-user moderation history, approval rates, and analytics in the dashboard.
    • source (string, optional): Source of the content (e.g., "web", "mobile")
    • session_id (string, optional): Session identifier
Example Request with user_id:
{
    "type": "text",
    "content": "Your content to moderate",
    "metadata": {
        "user_id": "user123",
        "source": "web"
    }
}

Including user_id in the metadata enables user-specific moderation tracking, stats, and review in the dashboard.

Response:
{
    "success": true,
    "content_id": "uuid-here",
    "status": "approved|rejected|flagged",
    "moderation_results": [
        {
            "decision": "rejected",
            "confidence": 0.95,
            "reason": "Content violates rule X",
            "moderator_type": "rule",
            "rule_id": "rule-uuid",
            "rule_name": "Rule Name",
            "processing_time": 1.23
        }
    ]
}

Response Formats

Success Response:
{
    "success": true,
    "content_id": "uuid",
    "status": "approved|rejected|flagged",
    "moderation_results": [...],
    "rule_matched": true,
    "total_rules_checked": 5,
    "fast_rules_checked": 2,
    "ai_rules_checked": 3
}
Error Response:
{
    "error": "Error message here",
    "success": false
}
Status Values:
  • approved: Content passed all moderation checks
  • rejected: Content violated rules and was rejected
  • flagged: Content needs human review
  • pending: Content is being processed
User Tracking:

Include a user_id in the metadata to track individual users and their moderation history:

{
    "type": "text",
    "content": "Content to moderate",
    "metadata": {
        "user_id": "user123",
        "source": "web"
    }
}

This enables:

  • User-specific moderation statistics
  • Approval rate tracking per user
  • Historical content review
  • Pattern analysis for problematic users

Error Handling

Common HTTP Status Codes:
Code Description Example
200 Success Content moderated successfully
400 Bad Request Missing required fields
401 Unauthorized Invalid or missing API key
403 Forbidden API key disabled or expired
500 Internal Server Error Server processing error

Code Examples

Here are examples of how to integrate with the AutoModerate API using different programming languages and tools:

import requests

url = "http://your-domain.com/api/moderate"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "am_your-api-key-here"
}
data = {
    "type": "text",
    "content": "Hello world!",
    "metadata": {"user": "test123"}
}

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

WebSocket Real-time Updates

Connect to WebSocket for real-time moderation updates:

Connection:
const socket = io('http://your-domain.com');

// Join project room
socket.emit('join_project', {project_id: 'your-project-id'});

// Listen for moderation updates
socket.on('moderation_update', function(data) {
    console.log('New moderation result:', data);
});
Update Event Format:
{
    "content_id": "uuid",
    "project_id": "project-uuid",
    "status": "approved|rejected|flagged",
    "content_type": "text",
    "content_preview": "Content preview...",
    "meta_data": {"user": "user123"},
    "results_count": 3,
    "processing_time": 1.23,
    "timestamp": "2025-01-01T12:00:00Z"
}
Event Fields:
  • content_id: Unique identifier for the content
  • project_id: Project the content belongs to
  • status: Final moderation decision
  • content_type: Type of content (text, image, video)
  • content_preview: Truncated preview of the content
  • meta_data: Additional metadata provided with the content
  • results_count: Number of moderation results generated
  • processing_time: Total processing time in seconds
  • timestamp: When the content was processed

Rate Limiting & Best Practices

Rate Limits:
  • 100 requests per minute per API key
  • 1000 requests per hour per API key
  • Concurrent requests are supported
Best Practices:
  • Store API keys securely
  • Use HTTPS in production
  • Implement proper error handling
  • Cache results when appropriate
  • Monitor your usage
Need Help? Check the dashboard for usage statistics and contact support if you need assistance.
{% endblock %}