Build moderation into your product

Quick start

Use Content-Type: application/json and set FILTERIT_BASE_URL to your deployment's origin. The public base URL is https://filterit.io.

cURL

# Configure an active deployment and a server-held API key.
# Local development: FILTERIT_BASE_URL=http://localhost:3000
curl "$FILTERIT_BASE_URL/api/v1/analyze" \
  -H "x-api-key: $FILTERIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your order arrived today. Thank you!",
    "options": { "mode": "fast", "strictness": "balanced" }
  }'

Server-side JavaScript

// Server-side JavaScript. Never expose this key in browser code.
const baseUrl = process.env.FILTERIT_BASE_URL;
const apiKey = process.env.FILTERIT_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Configure FilterIt on your server.");

const response = await fetch(new URL("/api/v1/analyze", baseUrl), {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": apiKey },
  body: JSON.stringify({
    text: "Your order arrived today. Thank you!",
    options: { mode: "fast", strictness: "balanced" }
  })
});
const body = await response.json();
if (!response.ok) {
  // Keep the request ID for diagnostics; do not log text or the API key.
  throw new Error(
    "FilterIt status " + response.status + ", request " + (body.requestId ?? "unknown")
  );
}

// A review result is a successful response that needs a policy/human decision.
if (body.data.decision === "allow") publishContent();
else if (body.data.decision === "review") queueForReview(body.requestId);
else rejectContent(body.requestId);

Python

# Python standard library; run on your server.
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(
    os.environ["FILTERIT_BASE_URL"].rstrip("/") + "/api/v1/analyze",
    data=json.dumps({
        "text": "Your order arrived today. Thank you!",
        "options": {"mode": "fast"}
    }).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["FILTERIT_API_KEY"]
    },
    method="POST"
)
try:
    with urlopen(request, timeout=15) as response:
        body = json.load(response)
except HTTPError as error:
    body = json.load(error)
    raise RuntimeError(
        f"FilterIt status {error.code}, request {body.get('requestId', 'unknown')}"
    ) from None

# Apply your product policy to body["data"]["decision"].
# Do not retry automatically: requests have no idempotency guarantee.

Modes, quotas, and credits

The default fast quota is 1,000 requests per account per 24-hour window. The default rate limit is 120 requests per minute across the account. Windows start with the first request after the previous window expires. All API keys and playground requests share these limits. Operators may configure different limits, and provider-wide caps can also make the service unavailable.

// Only thorough requests incur a length surcharge.
lengthCredits = Math.max(0, Math.ceil((text.length - 512) / 512));
thoroughCredits = 1 + 1 + lengthCredits;
fastCredits = 0;

Thorough credits are reserved before analysis and refunded when analysis fails. If a worker stops before settlement, the reservation has a 10-minute lease; an expired reservation is reconciled when the account next makes a request. There is no automatic idle-account refund timer. A successful review decision still counts as completed analysis. Check creditsConsumed and creditBreakdown in the response. meta.aiUsed can be true for free TypeSafe calls; it is not a billing flag.

Authentication and API keys

Sign in, open API keys, and deliberately create a key for your integration. A full key is shown once; subsequent views show a masked value. FilterIt stores a hash for authentication. Store the key in your server's secret configuration and send it in the x-api-key header.

Use separate named keys for integrations, monitor their usage, and revoke a key when it is compromised or no longer needed. An account can have at most 20 active keys; revoke an unused key before creating another when the limit is reached. Revocation prevents future requests from authenticating. It does not cancel work that has already started.

Dashboard session cookies do not authenticate the public API. CORS support does not protect an embedded API key: do not put keys in frontend bundles, public mobile clients, query strings, or logs. Call FilterIt from your backend. The signed-in playground uses your account session and shares your usage limits.

Request options

Paid thorough request

{
  "text": "You are an idiot.",
  "options": {
    "mode": "thorough",
    "detectProfanity": true,
    "filterProfanity": false,
    "detectTone": true,
    "customCategories": ["personal_insult"],
    "strictness": "balanced"
  }
}

Custom categories become independent semantic questions in the TypeSafe base pipeline. Multiple labels can match; they are not exclusive classes. The local development heuristic cannot establish arbitrary semantic custom categories. Advanced AI can return findings for the labels; it does not rewrite the base category scores. A label alone is not a trained policy or a reliable detector for PII, legal risk, or regulated content. Validate each label and threshold against representative synthetic examples before depending on it.

Category names are retained in usage metadata. Use policy labels, and keep personal information and confidential text out of label names.

Decisions, categories, and uncertainty

Each category has name, matched, and score. Arrays are ordered by score, not by an exclusive winning category. More than one category can match the same text. matched means the score reached the selected block threshold; a lower score can still cause a review decision. Inspect meta.coverage for assessed category/profanity checks.

These are current application policy thresholds, pending validation on labeled examples. A score at or above the block threshold blocks; otherwise any score at or above the review threshold requires review. Limited development coverage also requires review. Advanced findings can escalate an allow result to review, and cannot override a base block.

The TypeSafe base result uses uncalibrated probability scores; heuristic scores are weaker signals. Neither should be interpreted as measured accuracy or a calibrated probability of real-world harm. Quoted words, reclaimed language, sarcasm, misspellings, obfuscation, multilingual content, and context can change the correct decision. A missing match or finding does not establish that the text is safe.

Response reference

A successful response has a top-level data object, request ID, and billing fields. Errors also include a request ID. Use data.decision for workflow routing and retain the request ID for diagnostics.

{
  "data": {
    "safe": false,
    "decision": "review",
    "summary": "Content requires review; the classification is uncertain or limited.",
    "findings": [],
    "profanity": {
      "detected": false,
      "score": 0,
      "severity": "none",
      "confidence": 0,
      "matches": []
    },
    "tone": {
      "label": "neutral",
      "confidence": 0.2
    },
    "categories": [
      {
        "name": "toxicity",
        "matched": false,
        "score": 0
      },
      {
        "name": "harassment",
        "matched": false,
        "score": 0
      },
      {
        "name": "hate",
        "matched": false,
        "score": 0
      },
      {
        "name": "violence",
        "matched": false,
        "score": 0
      },
      {
        "name": "sexual_content",
        "matched": false,
        "score": 0
      },
      {
        "name": "self_harm",
        "matched": false,
        "score": 0
      },
      {
        "name": "spam",
        "matched": false,
        "score": 0
      }
    ],
    "meta": {
      "model": "heuristic-dev-v2",
      "provider": "heuristic",
      "advancedProvider": "none",
      "policyVersion": "filterit-policy-2",
      "reviewReasons": [
        "limited_classification"
      ],
      "scoreInterpretation": "heuristic_signal",
      "coverage": [
        "toxicity",
        "harassment",
        "hate",
        "violence",
        "sexual_content",
        "self_harm",
        "spam",
        "profanity"
      ],
      "mode": "fast",
      "aiUsed": false,
      "terminatedEarly": false,
      "cacheHit": false,
      "latencyMs": 1
    }
  },
  "requestId": "example-request-id",
  "creditsConsumed": 0,
  "creditBreakdown": {
    "mode": "fast",
    "textLength": 36,
    "baseCredits": 0,
    "aiCredits": 0,
    "lengthCredits": 0,
    "totalCredits": 0
  },
  "creditsRemaining": 500
}

Thorough findings and excerpt offsets

Thorough analysis can return findings[] with a category, exact input excerpt, offsets, and explanation. FilterIt checks that each accepted finding's text equals the corresponding input substring. This confirms the excerpt came from the input; it does not establish that the category or explanation is correct, or that every offense was found.

// Illustrative finding shape, not a measured provider result.
// Submitted text: "You are an idiot."
{
  "category": "harassment",
  "text": "idiot",
  "start": 11,
  "end": 16,
  "explanation": "An insult directed at another person."
}

// Offsets use JavaScript UTF-16 code units and an exclusive end.
inputText.slice(finding.start, finding.end) === finding.text

Do not normalize, trim, or otherwise change the input before applying its offsets. Emoji can occupy two UTF-16 code units. Python string indexes and UTF-8 byte indexes differ from these offsets; convert them before highlighting text. Fast TypeSafe decisions do not produce spans or profanity matches. Filtering requires thorough mode with profanity detection enabled; only accepted profanity findings are masked, and other unsafe content can remain.

Limits, headers, and errors

Text is limited to 4,000 UTF-16 code units and the JSON body to 64 KiB. Send one JSON object per request. Authentication, validation, quota, and provider failures return non-2xx statuses. A successful review decision uses HTTP 200.

Error bodies include error (a human-readable message), code (a machine-readable cause), and requestId. Validation failures can include details, while credit failures include requiredCredits and estimatedCost. Do not match error message text to decide whether to retry.

// Example authentication error shape (request ID is illustrative).
{
  "error": "Missing API key. Send the x-api-key header.",
  "code": "missing_api_key",
  "requestId": "example-request-id"
}

Rate/quota checks can count attempts even if a later step fails. Do not rely on retries being free. There is no supported idempotency key: retrying after an ambiguous timeout can duplicate a completed request and its paid charge. Use bounded retries with backoff only when your application accepts this behavior; authentication/validation errors need a corrected request.

Privacy, retention, and provider coverage

Request history records completed results and authenticated failures using metadata: request ID, HTTP status, sanitized error code, decision/category signals where available, character count, latency, provider identifiers, cache status, and credit usage. They do not retain submitted text, excerpts, model explanations, profanity matches, or filtered text. Only the owning account can view its usage and keys.

Classification caching is disabled by default. An operator can explicitly enable a retention TTL; that cache stores full results, which can include filtered text and excerpts. It is scoped by tenant, provider, model, and policy, and does not cache review decisions. Expiry stops reuse; database expiry alone does not guarantee physical deletion. Legacy records from older builds can contain payload-derived data and need a separate retention review.

TypeSafe supplies base category probabilities rather than exact offending spans or rationales. OpenAI is the currently supported optional advanced provider; disabled advanced analysis returns 503. Local development heuristics offer limited coverage and cannot automatically allow content.

Enabled providers receive the submitted text and selected category questions. Their own processing and retention terms apply; metadata-only FilterIt usage logs do not establish zero provider retention. Before submitting customer data, confirm provider activation, processing arrangements, and suitability for your privacy requirements. No universal accuracy, latency, multilingual coverage, or sensitive-data guarantee is made.

Debugging and integration checks

Open Usage and requests to review your account's request metadata. Use the request ID from the JSON body or response header to correlate a completed request or an authenticated error. Failure records include HTTP status and a sanitized error code, without retaining the payload or provider error body. Missing/invalid-key attempts cannot be associated with an account. If the database is unavailable, a failure record may also be unavailable; keep the client-side request ID, error code, and HTTP status without recording the payload.

Test your integration with synthetic clean, clearly flagged, quoted, obfuscated, ambiguous, and multiple-category text. Verify all three decision paths, 401/402/429/503 behavior, key revocation, and failure/refund handling. Compare false positives and false negatives against your own policy before relying on automation. Share request IDs and status codes for debugging; avoid sharing API keys or real customer text.