Policies

Overview

Moderation configurations (also called policies) define how content is moderated within your application. Each configuration specifies which moderation engines are active, what rules apply to detected content categories, and what actions to take when rules are triggered. Configurations are identified by a unique key and can be scoped to specific teams for multi-tenancy support.

You can combine multiple moderation engines in a single configuration -- for example, AI text analysis for detecting harassment, blocklists for filtering profanity, and image moderation for detecting nudity. Each engine has its own set of rules that map detected labels or patterns to actions such as flagging, removing, or shadow-blocking content.

After you change a policy, use Evaluations to re-run a fixed batch of content and see what improved or drifted.

Upsert Config

Creates or updates a moderation configuration. If a configuration with the specified key already exists, it will be replaced. A configuration can include any combination of moderation engines: AI text analysis, AI image moderation, blocklist filtering, toxicity detection, platform circumvention detection, velocity filters, and video call rules.

client.moderation().upsert_config(
    key="my_config",
    ai_text_config=AITextConfig(
        rules=[
            AITextRule(label="SPAM", action="flag"),
            AITextRule(label="HARASSMENT", severity_rules=[
                SeverityRule(severity="low", action="flag"),
                SeverityRule(severity="high", action="remove"),
            ]),
        ],
    ),
    block_list_config=BlockListConfig(
        rules=[BlockListRule(name="profanity_en", action="remove")],
    ),
    ai_image_config=AIImageConfig(
        rules=[AIImageRule(label="Non-Explicit Nudity", action="flag")],
    ),
)

Request Parameters

Config Key Conventions

The config key follows a hierarchical naming convention that determines its scope:

• Chat channel: chat:messaging:channel_id -- applies to a specific channel
• Chat channel type: chat:messaging -- applies to all channels of a given type
• All chat channels: chat -- applies to all chat channels
• Activity Feeds: feeds:default -- applies to activity feeds
• Polls: polls:default -- applies to poll text (questions, options and answers); see Moderate poll text

When content is submitted for moderation, the system looks for the most specific config key first, then falls back to broader scopes.

Get Config

Retrieve a specific moderation configuration by its key. Returns the full configuration object including all engine settings and rules.

client.moderation().get_config("my_config")

Request Parameters

Response

Delete Config

Delete a moderation configuration. Once deleted, any content moderation checks referencing this config key will no longer apply.

client.moderation().delete_config("my_config")

Request Parameters

Query Configs

Search and filter moderation configurations with support for sorting and pagination. Use this endpoint to list all configurations or find specific ones matching filter criteria.

client.moderation().query_moderation_configs(
    filter={},
    sort=[{"field": "created_at", "direction": -1}],
    limit=10,
)

Request Parameters

Response

Config Structure Reference

Each moderation configuration can include one or more engine-specific sub-configurations. The following table summarizes the available config types and where to find detailed documentation for each engine.

LLM config

llm_config sets up the AI Text (LLM) engine. Upserting the config replaces the whole llm_config, so send every field you want to keep.

LLM severity rules

severity_rules is an array of { severity, action }, with severity one of low, medium, high or critical. When the verdict's severity has a severity rule, that action is used; otherwise the rule's own action applies. For example, { "severity": "low", "action": "flag" } sends low-severity matches to review instead of removing them.

Rule Actions

Each rule within a config maps a detected label or pattern to an action. The following actions are available:

Severity Levels

For AI text analysis rules, you can define severity-based rules instead of a single action. This allows different actions depending on how severe the detected violation is. The available severity levels are:

When using severity rules, each severity level can be mapped to a different action. For example, you might flag low-severity harassment but automatically remove high-severity harassment, as shown in the Upsert Config example above.