API Documentation

Introduction

The Moderation API is a powerful REST API that helps you automatically detect and filter harmful content in user-generated text. Built on REST principles, we enforceHTTPS in every request to ensure data security, integrity, and privacy.

All requests use the following base URL:

Quick Start

Get up and running with the Moderation API in just a few minutes. Follow these simple steps:

curl -X POST https://api.sereinmod.com/v1/moderate/text \
  -H "x-api-key: mod_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, world!"}'

Authentication

All API requests require authentication using an API key. Include your API key in thex-api-key header with every request.

POST /v1/moderate/text

Send text content to be evaluated using your project's moderation settings. Returns detailed probability scores for multiple harmful content categories and a final decision.

{
  "content": "string",        // Required: Text to moderate (max 10,000 characters)
  "meta_data": {              // Optional: Additional metadata to store with the log
    "user_id": "123",
    "session_id": "abc",
    "ip_address": "192.168.1.1"
  }
}

{
  "final_decision": "denied",
  "model_output": {
    "toxic": 0.87,
    "severe_toxic": 0.92,
    "obscene": 0.78,
    "threat": 0.03,
    "insult": 0.45,
    "identity_hate": 0.65
  }
}

fetch('https://api.sereinmod.com/v1/moderate/text', {
  method: 'POST',
  headers: {
    'x-api-key': 'mod_xxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Hello, this is a test message!'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Moderation Categories

The API evaluates content across six distinct categories. Each category returns a probability score between 0.0 and 1.0, where higher scores indicate a greater likelihood of harmful content.

Understanding Thresholds

Thresholds determine when content is flagged. For each enabled category, if the probability score meets or exceeds the threshold, the content is denied.

Webhooks

Webhooks allow you to receive real-time notifications when moderation events occur. Instead of polling the API, you can configure webhooks to automatically notify your server when content is approved, denied, or when decisions are changed.

Webhook Events

The following events can be configured to trigger webhooks. You can enable or disable specific events based on your needs.

{
  "event_type": "content.approved",
  "log_id": "uuid-here",
  "decision": "approved",
  "content": "The original content text",
  "model_output": {
    "toxic": 0.2,
    "severe_toxic": 0.1,
    "obscene": 0.15,
    "threat": 0.05,
    "insult": 0.1,
    "identity_hate": 0.08
  },
  "metadata": {},
  "timestamp": "2025-01-15T10:30:00Z"
}

{
  "event_type": "content.denied",
  "log_id": "uuid-here",
  "decision": "denied",
  "content": "The original content text",
  "model_output": {
    "toxic": 0.87,
    "severe_toxic": 0.92,
    "obscene": 0.78,
    "threat": 0.03,
    "insult": 0.45,
    "identity_hate": 0.65
  },
  "metadata": {},
  "timestamp": "2025-01-15T10:30:00Z"
}

{
  "event_type": "decision.changed",
  "log_id": "uuid-here",
  "old_decision": "denied",
  "new_decision": "approved",
  "content": "The original content text",
  "timestamp": "2025-01-15T10:30:00Z"
}

Setting Up Webhooks

Configure webhooks for your project through the dashboard. You'll need to provide a URL endpoint that can receive POST requests and select which events you want to receive.

Webhook Signature Verification

All webhook requests include an X-Webhook-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request is authentic.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const payloadString = JSON.stringify(payload);
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payloadString);
  const expectedSignature = 'sha256=' + hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook endpoint
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  console.log('Webhook received:', req.body);
  res.status(200).send('OK');
});

Webhook Management

Webhook configuration is managed through the dashboard. Navigate to your project settings to configure webhooks, view delivery history, and test your webhook endpoint. The API endpoints below are available for programmatic access but require web authentication.

Rate Limits

API requests are rate limited to ensure fair usage and optimal performance for all users. Rate limit information is included in response headers.

Error Handling

The API uses standard HTTP status codes and returns error details in the response body. Always check the status code and handle errors appropriately in your application.

{
  "detail": "Error message describing what went wrong"
}

async function moderateContent(content) {
  try {
    const response = await fetch('https://api.sereinmod.com/v1/moderate/text', {
      method: 'POST',
      headers: {
        'x-api-key': 'mod_xxxxxxxxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ content })
    });

    if (!response.ok) {
      const error = await response.json();
      if (response.status === 429) {
        // Rate limit exceeded - implement retry with backoff
        throw new Error('Rate limit exceeded. Please try again later.');
      }
      throw new Error(error.detail || 'Moderation request failed');
    }

    return await response.json();
  } catch (error) {
    console.error('Moderation error:', error);
    throw error;
  }
}

HTTP Response Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

Best Practices