> For the complete documentation index, see [llms.txt](https://docs.wproofreader.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wproofreader.com/v6.12.0/api-reference/custom-dictionary-api/overview.md).

# Overview

Use the custom dictionary API to manage **shared, organization-owned wordlists**.

Words in an enabled custom dictionary are treated as **correct** during spellcheck.

**Command name:** `custom_dictionary`

{% hint style="info" %}
An **access key** is **required** for this command. See [Access key](/v6.12.0/deployment/configuration/application-server/access-key.md).
{% endhint %}

### When to use it

Use custom dictionary when the wordlist is:

* Shared across many users
* Managed by admins or automation
* Split by language
* Part of a structured workflow (create, enable/disable, audit, delete)

Use [User custom dictionary API](/v6.12.0/api-reference/user-custom-dictionary-api.md) when the wordlist is:

* Owned by an end user
* Mutable at runtime
* Not tied to a language

### Key capabilities

* Create multiple named dictionaries.
* Assign a language per dictionary.
* Enable or disable a dictionary without deleting it.
* Add, remove, or replace a dictionary wordlist.
* List dictionaries (metadata) or fetch words (full wordlist).

### Key concepts

* **Dictionary ID (`id`)**
  * Numeric value assigned by the server.
  * Save it after `create`. You can’t manage the dictionary without it.
* **Description (`description`)**
  * Human-readable label.
  * Must be unique per account.
* **Language (`lang`)**
  * Language code like `en_US`.
  * A dictionary affects spellcheck for its language.
* **State (`state`)**
  * `true`: enabled and used in spellcheck.
  * `false`: disabled and excluded from spellcheck.

{% hint style="info" %}
Disabled dictionaries are excluded from spellcheck silently. They remain accessible via API.
{% endhint %}

### Limits and validation

#### Word rules

* Max **63** characters per word
* No spaces
* No punctuation or special characters

{% hint style="info" %}
Words are validated at request parse time. Invalid words reject the request before any action runs.
{% endhint %}

#### Limits

* Maximum **50** dictionaries per subscription
* Maximum **500 KB** per dictionary file

### Actions

<table data-view="cards"><thead><tr><th>Action</th><th data-card-target data-type="content-ref">Docs</th></tr></thead><tbody><tr><td>Create a dictionary</td><td><a href="/pages/Vog9x7eVoy8j8qZHjzlf">/pages/Vog9x7eVoy8j8qZHjzlf</a></td></tr><tr><td>Delete dictionaries</td><td><a href="/pages/pMtci7OmbVfZ5iaQ0Ukz">/pages/pMtci7OmbVfZ5iaQ0Ukz</a></td></tr><tr><td>Add or replace words</td><td><a href="/pages/ZRC1mqcYzTfR090xN0RF">/pages/ZRC1mqcYzTfR090xN0RF</a></td></tr><tr><td>Remove words</td><td><a href="/pages/fGtaCriw1GbwHq6xUWIS">/pages/fGtaCriw1GbwHq6xUWIS</a></td></tr><tr><td>Fetch a dictionary wordlist</td><td><a href="/pages/WJAEFBJ4SDMVeF5BK6u3">/pages/WJAEFBJ4SDMVeF5BK6u3</a></td></tr><tr><td>List dictionaries (metadata)</td><td><a href="/pages/XXY8O7bJw5wgqAKqyLbV">/pages/XXY8O7bJw5wgqAKqyLbV</a></td></tr><tr><td>Rename or enable/disable</td><td><a href="/pages/LLDxLJSvc5cAMJUwZ99O">/pages/LLDxLJSvc5cAMJUwZ99O</a></td></tr></tbody></table>

### Next steps

* Follow the end-to-end flow in [Getting started](/v6.12.0/api-reference/custom-dictionary-api/getting-started.md).
* Look up all inputs in [Parameters reference](/v6.12.0/api-reference/custom-dictionary-api/parameters-reference.md).
* Learn response semantics in [Response format](/v6.12.0/api-reference/custom-dictionary-api/response-format.md).

{% hint style="info" %}
`getdicts` returns metadata only.

Use `getwords` to fetch the actual word list.
{% endhint %}