> 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/actions/add-list-of-words-addwords.md).

# Add list of words (addwords)

Adds words to a dictionary.

Optionally replaces the entire dictionary wordlist.

### What it does

* Appends words from `wordlist` to the dictionary.
* When `overwrite=true`, replaces the entire wordlist.

### Required parameters

| Parameter  | Type    | Notes                     |
| ---------- | ------- | ------------------------- |
| `cmd`      | string  | `custom_dictionary`       |
| `action`   | string  | `addwords`                |
| `id`       | integer | Exactly one dictionary ID |
| `wordlist` | string  | Comma-separated words     |

### Optional parameters

| Parameter   | Type    | Notes                                                       |
| ----------- | ------- | ----------------------------------------------------------- |
| `overwrite` | boolean | Default: `false`. When `true`, replaces the whole wordlist. |
| `format`    | string  | `json` (default) or `xml`                                   |
| `callback`  | string  | JSONP wrapper (JSON only)                                   |

{% hint style="warning" %}
`overwrite=true` replaces the entire wordlist.

This is destructive.
{% endhint %}

### Request example (append)

```
cmd=custom_dictionary&action=addwords&id=101565&wordlist=GraphQL,Kubernetes,TypeScript
```

### Request example (overwrite)

```
cmd=custom_dictionary&action=addwords&id=101565&overwrite=true&wordlist=GraphQL,TypeScript
```

### Response example

The response `wordlist` contains only words that were newly added.

```json
{
  "result": [
    {
      "id": 101565,
      "lang": "en_US",
      "description": "Engineering terms",
      "wordlist": ["GraphQL", "Kubernetes", "TypeScript"],
      "status": "success",
      "message": ["Words added."]
    }
  ]
}
```

### Possible errors

* Missing `id` or `wordlist`.
* Multiple IDs passed (only one is allowed).
* Invalid words (length or characters).
* Dictionary file size limit exceeded (HTTP 409).

See [Errors reference](/v6.12.0/api-reference/custom-dictionary-api/errors-reference.md).

### Notes and edge cases

* Partial success is reported as `status=warning`.
* Words already present may be skipped and reported in `message`.
* Words already recognized as correct can be filtered out.