Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moderationapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
When to use a wordlist

In many cases Guidelines are a better solution because they understand context and intent, but wordlists are useful if you want to prevent specific words or phrases from being used on your platform.

​
Smart wordlists

Wordlists understand semantic meaning, so if you add the word YouTube to a wordlist, the model understands that Vimeo is similar and it can be flagged as well without you having to add Vimeo to the wordlist. It also means that the wordlist understands tense and plural forms without you having to add them. This is what makes our wordlists smarter than a simple match on a list of words.

​
Creating a wordlist

You can create a Wordlist in the Model Studio or directly from your project. You can add words to the Wordlist by either typing them in or uploading a CSV or Excel file with a list of words. When uploading a spreadsheet each column is treated as a separate item in the wordlist. Case insensitive The wordlist is case insensitive, and words you add are automatically converted to lowercase. Duplicate words are automatically removed. If you add the word apple twice, it will automatically be deduplicated. Adding phrases You can add phrases as well as single words. Phrases are matched exactly as you type them, but also work with semantic meaning. For example, if you add the phrase New York to the wordlist, it will also match NYC. Embedding processing If you add a lot of words at once, the wordlist will automatically process them in the background to understand semantic meaning. This can take a few minutes for large wordlists, and the wordlist will not detect words until this processing is complete.

​
Flagging threshold

Wordlist thresholds
As wordlists understand semantic meaning, you can set a flagging threshold that determines how similar a word needs to be for the wordlist to flag it. 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. We provide 4 presets, plus a custom option where you can enter any percentage between 0 and 100.
  • Exact match (100%): Return matches that are exactly the same as the words or phrases in the wordlist.
  • Same word (90%): Also return matches that contain typos or slight variations, but are otherwise the same word.
  • Similar word (>50%): Also return 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

Wordlists are usually used as a block list, but you can also configure them as a require list or as a pass list.

​
Block list

A match will cause the content to be flagged. Use it to prevent certain words from being used on your platform.

​
Require list

If the wordlist does not find a match, the content will be flagged. Use it to require certain words to be present in the content.

​
Pass

The content will never be flagged, even if it matches the wordlist. Matches are still returned, and masking still applies — useful when you only need the data for analysis or want to mask specific entities without flagging.

​
API response

Each wordlist linked to 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.
FieldDescription
idwordlist/<key> — identifies which wordlist this result is from
typeAlways entity_matcher for wordlists
flaggedWhether this wordlist caused the content to be flagged. Depends on the wordlist’s mode (block / require / pass)
flagged_fieldsFor 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 not flagged, try to lower the flagging threshold to see the similarity score. This might provide insights on how similar a word is perceived by the model. The project playground is a good way to quickly test and debug any model.

​
Legacy wordlist model

We previously offered wordlists as a separate model under the Pre-built models section. This model did not understand semantic meaning and was not as smart as the wordlists available today. We recommend using the wordlists feature instead as it is more flexible and smarter.