> ## 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.
# Wordlists
> Flag, require, or extract your own words and phrases with wordlists that understand semantic meaning, typos, and variations.
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](/policies/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](https://dash.moderationapi.com/models) 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](/api-reference/wordlist/list-wordlists).
## 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](/content-moderation/acting-on-responses) 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](/content-moderation/acting-on-responses). The policy `type` is `entity_matcher` and the `id` is `wordlist/` — the key you set when creating the wordlist.
| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `wordlist/` — 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` |
```json Response example theme={"theme":"nord"}
{
"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:
```javascript theme={"theme":"nord"}
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.