Simple Moderation API

Authentication

All requests use bearer token auth with an API key from your console. Keys can be rotated without downtime — old keys keep working until you revoke them.

Authorization: Bearer sk_live_...

POST /v1/moderate

Submit content for moderation against a named rule set. Returns a decision, an aggregate score, and a per-rule breakdown with evidence.

POST https://api.simplemoderation.com/v1/moderate
{
  "rule_set": "default",
  "content": {
    "type": "text",
    "text": "Selling iPhone 15 Pro. WhatsApp +49 176 8123 1188"
  }
}

Response shape

{
  "id": "dec_01HXKQ4M...",
  "decision": "allow" | "review" | "block",
  "score": 0.0 ... 1.0,
  "rule_set": "default",
  "results": [
    {
      "rule": "No phone numbers in listings",
      "matched": true,
      "confidence": 0.99,
      "evidence": ["+49 176 8123 1188"],
      "reason": "Detected German-format phone number."
    }
  ],
  "latency_ms": 1840,
  "cost_usd": 0.00012
}

Idempotency

Send an Idempotency-Key header to make retries safe. Replays return the original response with an Idempotency-Replayed: true header and are never billed twice.

Rule sets

A rule set is a named collection of plain-English rules plus the decision logic that aggregates them. Manage them in the console, reference them by slug in the API.

• block rules — matching blocks the content.
• review rules — matching routes to review.
• allow rules — matching marks the content as explicitly fine. Allow rules do not override a block or review from another rule; scoped per-rule carve-outs are on the roadmap.

Rule changes are live within seconds — the next API call uses the updated set.

Status & errors

Standard HTTP status codes. 401 for bad keys, 402 with error.code = "quota_exceeded" when your monthly decision quota is reached, 404 for unknown rule sets. All errors return a stable error.code and a human-readable error.message.

Roadmap

• Audio & video — transcription + frame sampling, same response shape (modality_not_yet_available until then).
• Webhooks — async delivery for long-running and batch jobs.
• Rule set versioning — shadow-mode A/B tests against live traffic.
• SDKs — TypeScript and Python clients. Today the HTTP API is the interface; it is a single POST request.