Documentation

Build with OmniMod

Start with a Free account, create an API key, run your first moderation request, then use the dashboard to tune policy, inspect events, and manage usage.

Get started

First moderation request

  1. Create a Free account from the dashboard.
  2. Create an API key and copy the raw key once.
  3. Call POST /v1/moderations with Authorization: Bearer <api_key>.
  4. Review usage, quota, policy, and moderation events in the dashboard.
curl -X POST http://127.0.0.1:8000/v1/moderations \
  -H 'Authorization: Bearer omad_test_...' \
  -H 'Content-Type: application/json' \
  -d '{"modality":"text","input":"hello community"}'
API reference

Core API contract

Authentication

Use OmniMod API keys as bearer tokens. Raw keys are shown once, stored as HMAC hashes, and can be revoked or rotated from the dashboard.

Moderation

POST /v1/moderations accepts text requests today and returns a normalized allow, flag, or block decision with analyzer scores and request metadata.

Errors

Expect 401 for invalid keys, 403 for disabled organizations, 429 for rate limits or monthly quota exhaustion, and 5xx for service failures.

Request schema

{
  "modality": "text",
  "input": "string, 1-10000 chars",
  "language": "auto",
  "policy": "optional policy slug or id",
  "force_fresh": false,
  "metadata": {
    "external_id": "optional string metadata"
  }
}

Response schema

{
  "id": "moderation event id",
  "request_id": "request id from x-request-id or generated by OmniMod",
  "decision": "allow | flag | block",
  "engine_action": "allow | warn | review | block",
  "modality": "text",
  "severity": "none | low | medium | high | critical",
  "scores": {
    "profanity": 0.0,
    "spam": 0.0,
    "pattern_toxicity": 0.0,
    "url_evasion": 0.0,
    "language": 0.0
  },
  "analyzer_results": [
    {
      "analyzer": "spam",
      "score": 0.91,
      "severity": "high",
      "flagged": true,
      "matched_tokens": ["cheap followers"]
    }
  ],
  "policy": {
    "id": "policy id",
    "version_id": "policy version id",
    "version": 3
  },
  "provider": "omnimod-engine",
  "provider_version": "omnimod-engine-v1",
  "provider_status": "complete | degraded | failed_closed",
  "degraded_reason": null,
  "routing": {
    "mode": "rules_only | rules_plus_llm | cache_hit",
    "reason": "rules_clear"
  },
  "language": {
    "detected": "en | es | fr | de | unknown | mixed",
    "confidence": 1.0
  },
  "provider_usage": {
    "text_llm_credits": 0
  },
  "processing_time_ms": 42.5,
  "created_at": "2026-05-03T05:59:21.000Z",
  "cache": {
    "status": "hit | miss",
    "content_hash": "sha256:..."
  }
}

Error schemas

401 Invalid API key
{
  "detail": "Invalid API key"
}

429 Monthly quota exceeded
{
  "detail": {
    "code": "quota_exceeded",
    "message": "Monthly moderation quota exceeded",
    "plan_tier": "free",
    "monthly_request_quota": 100,
    "used": 100,
    "remaining": 0
  }
}

429 Rate limited
{
  "detail": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "limit": 60,
    "remaining": 0,
    "reset_seconds": 60
  }
}
SDKs

Python first, TypeScript next

The Python SDK covers text moderation with typed response helpers and API error classes. TypeScript is planned next for Node and frontend-adjacent integrations after the contract is locked with OpenAPI.

Python SDK

from omnimod_sdk import OmniModClient

client = OmniModClient(
    api_key="omad_live_...",
    base_url="https://api.omnimod.net",
)

result = client.moderate_text(
    "hello community",
    policy="community-default",
)

if result.is_blocked:
    print("blocked", result.severity)

TypeScript SDK

Planned after the OpenAPI contract is published so browser, Node.js, and integration customers get the same request and response model.

Dashboard guide

Customer operations

  • Overview: quota, request volume, and recent moderation health.
  • API Keys: create, rotate, revoke, and copy raw keys only at creation or rotation.
  • Moderation: manually test API keys, select policies, and inspect persisted event details.
  • Policies: enable analyzers, tune thresholds, version changes, and control hash reuse.
  • Usage and Billing: monitor monthly quota and manage Stripe plan state.
Policies

Control moderation behavior

OmniMod provides the moderation intelligence. You set the enforcement posture for your product and audience.

  • Default policies apply when no policy selector is sent.
  • Analyzer toggles control profanity, spam, evasion, language, emoji, URL, formatting, transliteration, and NSFW checks.
  • Policy versions are immutable so historical moderation events keep their original policy context.
  • Hash reuse avoids recomputing duplicate content unless customers send force_fresh.
Language support

Production, beta, and fallback coverage

Language metadata is detected automatically. Customers do not need to pass a language value for normal moderation requests.

English

First-class production moderation with rules, semantic routing, and the strongest benchmark target.

Spanish, French, German

Beta / Early Access coverage with high-confidence rule packs plus semantic provider routing for ambiguity and context.

Other languages

Semantic fallback is available when the provider is enabled, but accuracy can vary while benchmarking and language-specific rule work continues.

Unknown or mixed text

OmniMod records language metadata and routes low-confidence or mixed-language text to semantic review instead of blocking it solely because of language.

Billing and limits

Plans and quota

Free

100 moderation requests per month for evaluation and prototyping.

Packages

Developer, Launch, and Growth use fixed monthly quotas through Stripe Checkout and Customer Portal.

Flex

Flex is the planned usage-based path for high or variable volume with explicit image moderation opt-in.

Quota behavior

Free, Developer, Launch, and Growth enforce organization monthly quota. Cache hits count for MVP and exhausted quota returns 429.

Semantic moderation

OmniMod records semantic provider usage separately from standard requests. Rules run first to reduce latency and cost, but usage accounting does not silently weaken semantic coverage.

Security

Trust boundaries

  • Microsoft Entra External ID owns customer authentication.
  • OmniMod never stores customer dashboard passwords.
  • Raw API keys are not stored and are returned only once.
  • Moderation events store metadata, scores, and content hashes, not raw submitted text.
  • Internal admin access is gated by Entra app roles and reasoned audit events.
Roadmap

Coming next

OpenAPI

Publish the formal API specification and generated reference once the core contract stabilizes.

SDKs

Python SDK is available as an MVP package. TypeScript SDK and OpenAPI-generated reference remain next.

Moderation coverage

Multilingual text and image moderation are planned for the next provider integration phase.