AutoModerate/docs/api/moderation.md

Content Moderation API

The Content Moderation API allows you to submit content for automated moderation and retrieve moderation results.

Submit Content for Moderation

Submit content to be analyzed by your project's moderation rules.

Endpoint

POST /api/moderate

Headers

Content-Type: application/json
X-API-Key: your-api-key

Request Body

{
  "type": "text",
  "content": "The content to be moderated",
  "metadata": {
    "user_id": "optional-user-id",
    "source": "comment_system",
    "custom_field": "custom_value"
  }
}

Parameters

Field	Type	Required	Description
type	string	No	Content type (defaults to "text")
content	string	Yes	The actual content to moderate
metadata	object	No	Additional information about the content

Metadata Fields

The metadata object can contain any custom fields. If user_id is provided, AutoModerate will track per-user statistics.

Response

{
  "success": true,
  "content_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "approved",
  "moderation_results": [
    {
      "decision": "approved",
      "confidence": 0.95,
      "reason": "Content passed all moderation checks",
      "moderator_type": "rule",
      "rule_name": "Safe Content Rule",
      "processing_time": 0.15
    }
  ]
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
content_id	string	Unique identifier for the moderated content
status	string	Moderation decision: approved, rejected, flagged
moderation_results	array	Detailed results from moderation process

Example Requests

Simple Text Moderation

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "type": "text",
    "content": "This is a great product! I love it."
  }' \
  http://localhost:6217/api/moderate

Content with User Tracking

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "Check out this amazing deal!",
    "metadata": {
      "user_id": "user_12345",
      "source": "product_review"
    }
  }' \
  http://localhost:6217/api/moderate

Get Content Details

Retrieve detailed information about previously moderated content.

Endpoint

GET /api/content/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the content

Response

{
  "success": true,
  "content": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "project_id": "proj_abc123",
    "content_type": "text",
    "content_data": "The original content",
    "meta_data": {
      "user_id": "user_12345",
      "source": "comments"
    },
    "status": "approved",
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:01",
    "moderation_results": [
      {
        "decision": "approved",
        "confidence": 0.95,
        "reason": "Content passed all checks",
        "moderator_type": "rule",
        "created_at": "2024-01-15T10:30:01"
      }
    ]
  }
}

Example

curl -H "X-API-Key: your-api-key" \
  http://localhost:6217/api/content/123e4567-e89b-12d3-a456-426614174000

List Content

Retrieve a paginated list of moderated content.

Endpoint

GET /api/content

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page (max: 100)
status	string	-	Filter by status: approved, rejected, flagged

Response

{
  "success": true,
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "project_id": "proj_abc123",
      "content_type": "text",
      "content_data": "The content text",
      "meta_data": {
        "user_id": "user_12345"
      },
      "status": "approved",
      "created_at": "2024-01-15T10:30:00",
      "updated_at": "2024-01-15T10:30:01",
      "moderation_results": []
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 5,
    "per_page": 20,
    "total": 100,
    "has_next": true,
    "has_prev": false
  }
}

Example Requests

Get All Content

curl -H "X-API-Key: your-api-key" \
  http://localhost:6217/api/content

Get Rejected Content

curl -H "X-API-Key: your-api-key" \
  "http://localhost:6217/api/content?status=rejected&page=1&per_page=50"

Get Project Statistics

Retrieve basic statistics for your project's moderation activity. See Project Statistics API for detailed documentation.

Endpoint

GET /api/stats

Headers

X-API-Key: your-api-key

Example Request

curl -H "X-API-Key: your-api-key" \
  http://localhost:6217/api/stats

Health Check

Check the API service status.

Endpoint

GET /api/health

Note: This endpoint does not require authentication.

Response

{
  "status": "healthy",
  "service": "AutoModerate API",
  "version": "1.0.0"
}

Example

curl http://localhost:6217/api/health

API Documentation

Access the web-based API documentation.

Endpoint

GET /api/docs

This endpoint returns an HTML page with interactive API documentation.

Authentication

All API endpoints (except /health and /docs) require authentication using an API key.

API Key Header

Include your API key in the request header:

X-API-Key: your-api-key-here

Getting an API Key

1. Log in to the AutoModerate dashboard
2. Navigate to your project
3. Go to "API Keys" section
4. Click "Generate New Key"
5. Copy and securely store your key

Error Responses

Authentication Errors

Missing API Key

{
  "error": "API key required"
}

HTTP Status: 401

Invalid API Key

{
  "error": "Invalid API key"
}

HTTP Status: 401

Request Errors

Missing JSON Data

{
  "error": "JSON data required"
}

HTTP Status: 400

Missing Content

{
  "error": "Content data required"
}

HTTP Status: 400

Content Not Found

{
  "error": "Content not found"
}

HTTP Status: 404

Server Errors

Internal Server Error

{
  "error": "Internal server error"
}

HTTP Status: 500

Moderation Statuses

AutoModerate uses four primary statuses for content:

• pending: Content is being processed
• approved: Content passed all moderation rules
• rejected: Content violated one or more moderation rules
• flagged: Content requires manual review

Content Types

Currently supported content types:

• text: Plain text content (default)

Best Practices

1. Always Handle Errors

import requests

response = requests.post('/api/moderate', 
    headers={'X-API-Key': 'your-key'},
    json={'content': 'test content'}
)

if response.status_code == 200:
    data = response.json()
    if data['success']:
        print(f"Content {data['content_id']}: {data['status']}")
    else:
        print(f"Error: {data.get('error', 'Unknown error')}")
else:
    print(f"HTTP Error: {response.status_code}")

2. Use Metadata for Tracking

Include useful metadata to track content sources and users:

{
  "content": "User comment text",
  "metadata": {
    "user_id": "user_12345",
    "source": "comment_system",
    "post_id": "post_67890",
    "ip_address": "192.168.1.1"
  }
}

3. Implement Pagination

When listing content, always use pagination:

# Start with page 1
curl -H "X-API-Key: your-key" \
  "http://localhost:6217/api/content?page=1&per_page=50"

# Check pagination.has_next and continue if needed

4. Monitor Your Statistics

Regularly check your project statistics to understand moderation patterns:

curl -H "X-API-Key: your-key" \
  http://localhost:6217/api/stats

Next Steps

• WebSocket Events - Real-time moderation updates
• Installation Guide - Set up AutoModerate
• Architecture Guide - Understand the system