Wordlists

Wordlists let you moderate against your own list of words and phrases — brand names, competitor mentions, or terms specific to your community. Unlike a plain string match, wordlists understand semantic meaning: add YouTube and semantically similar words like Vimeo can be flagged too; add the phrase New York and it also matches NYC. Tense, plural forms, and slight variations are covered without you having to add every spelling yourself. Wordlists belong to your organization and are enabled per channel, so the same list can back several channels at once — editing it takes effect everywhere it’s used.

When to use a wordlist

Use a wordlist when the rule is about specific words or phrases: a list of brands, competitor names, or terms that should never (or always) appear. When the rule is about context and intent rather than particular words, Guidelines are usually the better choice — they evaluate what the content means, not which words it uses.

Creating a wordlist

Create wordlists in Model Studio under Wordlists, or directly from your project. Add entries by typing them in or by uploading a CSV or Excel file — each column in a spreadsheet is treated as a separate entry. Entries follow a few rules:

Case insensitive — entries are automatically converted to lowercase.
Deduplicated — adding apple twice keeps a single entry.
Phrases work too — a phrase is matched as you typed it, but with the same semantic understanding as single words.
Large uploads process in the background — adding many entries at once triggers processing that can take a few minutes, and the wordlist won’t detect words until it completes.

You can also manage entries programmatically with the wordlist API.

Flagging threshold

Because wordlists understand semantic meaning, you choose how similar a word needs to be before it’s flagged. Thresholds are set per channel — the same wordlist can be linked to multiple channels with a different threshold on each, so you can be stricter in some places than others. There are 4 presets, plus a custom option where you can enter any percentage between 0 and 100:

Exact match (100%): Only flag matches that are exactly the same as the words or phrases in the wordlist.
Same word (90%): Also flag matches that contain typos or slight variations, but are otherwise the same word.
Similar word (>50%): Also flag matches that are semantically similar to the words in the wordlist.
Nearest word (>10%): Always return matches, even if they are not semantically similar. Useful for debugging or finding the closest word in a text.

Flagging mode

Like the threshold, the mode is set per channel:

Mode	Behavior	Use it for
Block list	A match flags the content.	Preventing certain words from being used on your platform. This is the default.
Require list	Content is flagged when it does not contain a match.	Requiring certain words to be present, e.g. on-topic keywords.
Pass	Never flags, but matches are still returned and masking still applies.	Collecting match data for analysis, or masking specific entities without flagging.

In API responses

Each wordlist enabled on a channel returns its results inside the policies array of the moderation response. The policy type is entity_matcher and the id is wordlist/<key> — the key you set when creating the wordlist.

Field	Description
`id`	`wordlist/<key>` — identifies which wordlist this result is from
`type`	Always `entity_matcher` for wordlists
`flagged`	Whether this wordlist caused the content to be flagged. Depends on the wordlist’s mode (block / require / pass)
`flagged_fields`	For object submissions, which fields contained matches that triggered the flag
`matches[]`	The matched words. Each entry has `match` (the word), `probability` (similarity score 0–1), `span` (`[start, end]`), and `mask`

Response example

{
  "policies": [
    {
      "id": "wordlist/brandlist",
      "type": "entity_matcher",
      "flagged": true,
      "flagged_fields": [],
      "matches": [
        {
          "match": "youtube",
          "probability": 0.9999997615814209,
          "span": [12, 19],
          "mask": null
        }
      ]
    },
    {
      "id": "wordlist/test",
      "type": "entity_matcher",
      "flagged": false,
      "flagged_fields": [],
      "matches": []
    }
  ]
}

Read a specific wordlist result by its key:

const brandlist = response.policies.find(p => p.id === "wordlist/brandlist");

if (brandlist?.flagged) {
  brandlist.matches.forEach(m => console.log(`${m.match} at ${m.span}`));
}

Debugging wordlists

If you wonder why a word is or isn’t flagged, lower the flagging threshold to see the similarity score of the nearest match — this shows how similar the word is perceived to be. The project playground is a good way to quickly test and debug a wordlist.

Legacy wordlist model — we previously offered wordlists as a pre-built model. That model matched words literally without semantic understanding. If you still use it, we recommend switching to the wordlists feature described here — it’s smarter and more flexible.

Documentation

Learn

Resources

When to use a wordlist

Creating a wordlist

Flagging threshold

Flagging mode

In API responses

Debugging wordlists

​When to use a wordlist

​Creating a wordlist

​Flagging threshold

​Flagging mode

​In API responses

​Debugging wordlists

When to use a wordlist

Creating a wordlist

Flagging threshold

Flagging mode

In API responses

Debugging wordlists