CleanMod API Documentation

Authentication

All API requests require authentication using an API key. You can obtain an API key from your dashboard.

Include your API key in requests using one of the following methods:

Recommended: Authorization Header

Authorization: Bearer <API_KEY>

Alternative: Custom Header

x-api-key: <API_KEY>

⚠️ Security Warning

API keys are secret credentials. Never expose them in client-side JavaScript, public repositories, or client-side code. Always use server-side code or environment variables to store and use API keys.

Moderate Text

Analyze text content for toxicity, insults, threats, and other harmful content.

Endpoint

POST https://cleanmod.dev/api/v1/moderate

Content-Type

application/json

Request Body

{
  "text": "You are an idiot",
  "model": "english-basic"
}

text (required): The text content to moderate. Must be a non-empty string.

model (optional): The moderation model to use. Defaults to english-basic.

Response Body

{
  "id": "log_abc123...",
  "model": "english-basic",
  "provider": "unitary",
  "providerModel": "unitary/multilingual-toxic-xlm-roberta",
  "decision": "flag",
  "overall_score": 0.91,
  "threshold": 0.8,
  "categories": {
    "toxicity": 0.91,
    "insult": 0.88
  },
  "created_at": "2025-11-16T15:00:00.000Z"
}

id: Unique identifier for this moderation log entry.

decision: One of allow, flag, or block.

overall_score: Overall toxicity score (0-1), where higher values indicate more toxic content.

categories: Per-category scores for different types of harmful content.

WordPress – CleanMod Comment Moderation

Automatically check new comments using CleanMod and hold or spam comments based on the AI decision.

Installation

For now, install from GitHub:

Download from GitHub
Upload the plugin to /wp-content/plugins/
Activate through the WordPress admin Plugins menu

Once approved on WordPress.org, you'll be able to install it directly from your WP admin.

Configuration

Go to Settings → CleanMod in WordPress admin
Paste your API key from the CleanMod dashboard
Choose moderation behaviors:

When decision = "flag":

Hold for moderation (default)
Pass through (respects WordPress default settings)

When decision = "block":

Hold for moderation
Mark as spam

Note: If the API fails, the plugin fails open (doesn't break comment submission). Comments are sent as text only—no user identities are shared with CleanMod.

JavaScript SDK

CleanMod provides an official JavaScript/TypeScript SDK for easy integration in Node.js, serverless functions, and backend frameworks.

Installation

npm install @cleanmod/js

# or

yarn add @cleanmod/js

# or

pnpm add @cleanmod/js

Quick Example

import { createCleanModClient } from "@cleanmod/js";

const client = createCleanModClient({
  apiKey: process.env.CLEANMOD_API_KEY!,
});

const res = await client.moderate({
  text: "you are an idiot"
});

console.log(res);

The SDK uses the same moderation engine as the REST API and supports all models and future features.

Error Responses

The API returns standard HTTP status codes and JSON error responses.

400 Bad Request

Invalid or missing request body fields.

{
  "error": "Missing or invalid \"text\" field in request body."
}

401 Unauthorized

Missing or invalid API key.

{
  "error": "Missing API key. Use Authorization: Bearer <KEY> or x-api-key."
}

429 Too Many Requests

Monthly quota exceeded.

{
  "error": "Monthly quota exceeded. Upgrade your CleanMod plan to continue.",
  "quota": 2000,
  "used": 2000
}

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "Internal server error."
}

Code Examples

JavaScript SDK (@cleanmod/js)

import { CleanModClient } from "@cleanmod/js";

const client = new CleanModClient({
  apiKey: process.env.CLEANMOD_API_KEY!,
  // baseUrl is optional, defaults to https://cleanmod.dev
  baseUrl: "https://cleanmod.dev",
});

async function run() {
  const result = await client.moderate({
    text: "You are an idiot",
    model: "english-basic",
  });

  console.log(result.decision, result.overallScore);
}

run().catch(console.error);

cURL

curl -X POST https://cleanmod.dev/api/v1/moderate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "You are an idiot",
    "model": "english-basic"
  }'

Node.js (fetch)

const response = await fetch('https://cleanmod.dev/api/v1/moderate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'You are an idiot',
    model: 'english-basic',
  }),
});

const result = await response.json();
console.log(result);

Python (requests)

import requests

response = requests.post(
    'https://cleanmod.dev/api/v1/moderate',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'text': 'You are an idiot',
        'model': 'english-basic',
    },
)

result = response.json()
print(result)

PHP

<?php

$url = 'https://cleanmod.dev/api/v1/moderate';
$data = [
    'text' => 'You are an idiot',
    'model' => 'english-basic',
];

$options = [
    'http' => [
        'method' => 'POST',
        'header' => [
            'Authorization: Bearer YOUR_API_KEY',
            'Content-Type: application/json',
        ],
        'content' => json_encode($data),
    ],
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);

var_dump($result);

Open Source & SDKs

CleanMod provides official SDKs and integrations to make integration easier. All SDKs and plugins are open source.

JavaScript SDK – @cleanmod/js

Use this in Node.js / Next.js / serverless functions instead of hand-rolling fetch calls to /api/v1/moderate.

GitHub →npm →

WordPress Plugin – CleanMod – AI Comment Moderation

Automatically moderate WordPress comments using CleanMod. Once approved on WordPress.org you'll be able to install it directly from your WP admin.

GitHub →