API Documentation

Quick start

Get up and running in under 60 seconds.

curl -X POST https://api.safemoderation.com/.netlify/functions/moderate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "text",
    "content": "Hello, how are you today?",
    "reference_id": "comment_84729"
  }'

const response = await fetch(
  'https://api.safemoderation.com/.netlify/functions/moderate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SAFEMODERATION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_type: 'text',
      content: 'Hello, how are you today?',
      reference_id: 'comment_84729',
    }),
  }
);
const data = await response.json();
console.log(data.decision); // "allow"

import requests

response = requests.post(
    'https://api.safemoderation.com/.netlify/functions/moderate',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'media_type': 'text',
        'content': 'Hello, how are you today?',
        'reference_id': 'comment_84729',
    }
)
data = response.json()
print(data['decision'])  # "allow"

curl -X POST https://api.safemoderation.com/.netlify/functions/moderate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "image",
    "content": "https://example.com/user-upload.jpg",
    "reference_id": "post_a8f9c2"
  }'

const response = await fetch(
  'https://api.safemoderation.com/.netlify/functions/moderate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SAFEMODERATION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_type: 'image',
      content: 'https://example.com/user-upload.jpg',
      reference_id: 'post_a8f9c2',
    }),
  }
);
const data = await response.json();
console.log(data.decision); // "block"

import requests

response = requests.post(
    'https://api.safemoderation.com/.netlify/functions/moderate',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'media_type': 'image',
        'content': 'https://example.com/user-upload.jpg',
        'reference_id': 'post_a8f9c2',
    }
)
data = response.json()
print(data['decision'])  # "block"

{
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference_id": "comment_84729",
  "decision": "allow",
  "confidence": 0.95,
  "categories": {
    "hate_speech": 0.01,
    "harassment_bullying": 0.02,
    "adult_content": 0.00,
    "violence_gore": 0.00,
    "spam_scam": 0.01,
    "suicide_self_harm": 0.00,
    "pii_exposure": 0.00,
    "profanity": 0.00
  },
  "warnings": [],
  "usage": {
    "credits_used": 1,
    "monthly_credits": 15000
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "post_a8f9c2",
  "decision": "block",
  "confidence": 0.92,
  "categories": {
    "adult_content": 0.04,
    "violence_gore": 0.92,
    "hate_speech": 0.01,
    "suicide_self_harm": 0.00,
    "weapons": 0.78,
    "drugs": 0.00,
    "alcohol": 0.00,
    "tobacco": 0.00
  },
  "warnings": [],
  "usage": {
    "credits_used": 47,
    "monthly_credits": 15000
  }
}

Reference ID

reference_id is a required field that links each moderation result back to the record in your own data model. It is stored in the log and echoed in every response. It has no effect on the moderation decision itself.

Why reference_id is required

SafeModeration assigns its own request_id to every call. reference_id is yours: it makes the moderation log immediately actionable without a secondary lookup. When a result comes back block, your code already knows exactly which record to act on.

Worked example

A forum stores user comments in a comments table, each with an integer primary key. When a user submits a new comment, the forum's backend calls SafeModeration before writing the row to the database:

const result = await fetch(
  'https://api.safemoderation.com/.netlify/functions/moderate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SAFEMODERATION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_type: 'text',
      content: comment.body,
      reference_id: `comment_${comment.id}`,  // e.g. "comment_84729"
    }),
  }
).then(r => r.json());

if (result.decision === 'block') {
  // reference_id is echoed back, no extra lookup needed
  await markCommentRejected(result.reference_id);
}

The response echoes "reference_id": "comment_84729", so the forum can act on the result without tracking SafeModeration's internal request_id at all.

Metadata

The optional metadata field accepts any plain JSON object you want stored alongside the log record and echoed in the response. It has no effect on the moderation decision itself.

What to put in metadata

Metadata is a free-form envelope: use any keys that make sense for your platform. Common examples:

• content_type: your category for the content (e.g. comment, post, profile), useful for filtering in your moderation dashboard
• author_id: identifier of the user who created the content, enabling author-level abuse tracking and repeat-offender detection
• thread_id, locale, client_version: any other context your team finds useful when reviewing flagged content

Worked example

const result = await fetch(
  'https://api.safemoderation.com/.netlify/functions/moderate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SAFEMODERATION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_type: 'text',
      content: comment.body,
      reference_id: `comment_${comment.id}`,
      metadata: {
        content_type: 'comment',
        author_id: `user_${comment.authorId}`,
        thread_id: `thread_${comment.threadId}`,
      },
    }),
  }
).then(r => r.json());

// result.metadata is echoed back exactly as sent
console.log(result.metadata.author_id);  // "user_84729"

The metadata object is echoed in the response unchanged, so your downstream code can read any field it needs without an extra lookup.

Authentication

SafeModeration uses API key authentication. Pass your key as a Bearer token in the Authorization header on every request.

Authorization: Bearer sm_live_your_key_here

The /moderate endpoint

POST https://api.safemoderation.com/.netlify/functions/moderate

curl -X POST https://api.safemoderation.com/.netlify/functions/moderate \
  -H "Authorization: Bearer sm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "text",
    "content": "I know where you live. Im going to find you and hurt you.",
    "reference_id": "post_a8f9c2"
  }'

const response = await fetch(
  'https://api.safemoderation.com/.netlify/functions/moderate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SAFEMODERATION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_type: 'text',
      content: 'I know where you live. Im going to find you and hurt you.',
      reference_id: 'post_a8f9c2',
    }),
  }
);
const data = await response.json();
// data.decision === "block"

import requests

response = requests.post(
    'https://api.safemoderation.com/.netlify/functions/moderate',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'media_type': 'text',
        'content': 'I know where you live. Im going to find you and hurt you.',
        'reference_id': 'post_a8f9c2',
    }
)
data = response.json()
# data["decision"] == "block"

{
  "request_id": "9b2d3e4f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "reference_id": "post_a8f9c2",
  "decision": "block",
  "confidence": 0.97,
  "categories": {
    "hate_speech": 0.08,
    "harassment_bullying": 0.96,
    "adult_content": 0.00,
    "violence_gore": 0.45,
    "spam_scam": 0.01,
    "suicide_self_harm": 0.00,
    "pii_exposure": 0.00,
    "profanity": 0.02
  },
  "warnings": [],
  "usage": {
    "credits_used": 42,
    "monthly_credits": 15000
  }
}

Decisions explained

Every response includes a decision field. Here is how to act on each value:

Integration pattern

switch (data.decision) {
  case 'allow':
    return publishContent();
  case 'flag':
    return sendToHumanReview();
  case 'block':
    return rejectContent();
}

Confidence scores

The confidence field reflects overall certainty in the decision, from 0.00 (uncertain) to 1.00 (very certain). Individual category scores reflect how strongly each category applies to the content.

Text categories

When media_type is "text", the response includes scores for the following eight categories. Each value is a float from 0.00 to 1.00. All keys are always present.

Evasion detection

SafeModeration automatically detects common evasion techniques including l33tspeak substitution, spaced characters, Unicode homoglyphs, and repeated character patterns.

Multilingual support

The classifier detects harmful content in 50+ languages. Coverage is most thoroughly tested in English, Spanish, French, German, Portuguese, Arabic, and Russian, with strong performance across other major European, East Asian, South Asian, and Middle Eastern languages.

Image categories

When media_type is "image", the response includes scores for the following eight categories. Each value is a float from 0.00 to 1.00. All keys are always present.

Image requirements

SafeModeration fetches the image from the URL you provide, classifies it, then discards the bytes. We store the URL and a one-way hash of the image content for caching and audit purposes. The image bytes are not retained.

Error codes

Error response format

{
  "error": "Invalid or revoked API key."
}

Image errors include an additional code field:

{
  "error": "Image is not JPEG or PNG.",
  "code": "IMAGE_FORMAT_UNSUPPORTED"
}

Credits and rate limits

Credits

Each moderation request consumes credits from your monthly allowance:

Failed image requests do not consume credits. If the image cannot be fetched, is in an unsupported format, or fails any safety check, you are not charged.

Plans

Credits reset on the 1st of each calendar month. Unused credits do not roll over.

Rate limits

All plans share a burst limit of 600 requests per minute per API key. Exceeding this returns a 429 with a Retry-After header and a retry_after field in the response body indicating the seconds remaining in the current window.

Retry pattern

async function moderateWithRetry(content) {
  const res = await fetch(url, options);
  if (res.status === 429) {
    const data = await res.json();
    if (data.limit_type === 'monthly') throw new Error('Monthly limit reached');
    const wait = (data.retry_after ?? 60) * 1000;
    await new Promise(r => setTimeout(r, wait));
    return fetch(url, options);
  }
  return res;
}

FAQ