> 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/style-guide-api/actions/add-rule-addrule.md).

# Add rule (addrule)

Create a new style guide rule.

### Request

Use the shared HTTP API endpoint and request formats.

See [HTTP API Overview](/v6.12.0/api-reference/overview.md).

#### Parameters

| Parameter         | Type      | Required | Default       | Notes                                                            |
| ----------------- | --------- | -------- | ------------- | ---------------------------------------------------------------- |
| `cmd`             | string    | Yes      | `style_guide` | Command name.                                                    |
| `action`          | string    | Yes      | `addrule`     | Action name.                                                     |
| `lang`            | string    | No       | `common`      | Language scope to create the rule in (example: `en_US` or `en`). |
| `patterns`        | string\[] | Yes      |               | Patterns to match.                                               |
| `suggestions`     | string\[] | No       | \[]           | Replacement suggestions.                                         |
| `state`           | boolean   | No       | `true`        | Enables/disables the rule.                                       |
| `context_include` | string\[] | No       | \[]           | Matches only when one of these contexts exists.                  |
| `context_exclude` | string\[] | No       | \[]           | Skips matches when one of these contexts exists.                 |
| `description`     | string    | No       |               | Message shown to the user.                                       |
| `collection`      | string    | No       | `style guide` | A name of the collection in which rules are stored.              |

{% hint style="info" %}
You can’t choose a rule ID.

The rule ID is generated as a hash of `patterns` + `context_include`. If `patterns` or `context_include` changes later, the rule will get a new ID.
{% endhint %}

### Behavior

* Creates a new rule in the target style guide file.
* Returns the created rule in `result`.

### Response

Single rule object containing its rule ID is returned.

See [Response schema](/v6.12.0/api-reference/style-guide-api/response-schema.md).

### Errors

See

* [Errors](/v6.12.0/api-reference/style-guide-api/errors.md#addrule-errors).
* [Validation & limits](/v6.12.0/api-reference/style-guide-api/validation-and-limits.md)

### Examples

{% tabs %}
{% tab title="Example (JSON body)" %}

<details>

<summary>Request URL (on-premises)</summary>

{% code overflow="wrap" %}

```
http(s)://server_entry_point/?cmd=style_guide&access_key=<your-access-key>&collection=style guide&lang=en_US&action=addrule&patterns=["webspellchecker"]&suggestions=["WebSpellChecker"]
```

{% endcode %}

</details>

<details>

<summary>Request URL (Cloud)</summary>

{% code overflow="wrap" %}

```
https://svc.webspellchecker.net/api?cmd=style_guide&access_key=<your-access-key>&serviceid=<your-service-id>&collection=style guide&lang=en_US&action=addrule&patterns=["webspellchecker"]&suggestions=["WebSpellChecker"]
```

{% endcode %}

</details>

<details>

<summary>Request CURL (on-premises)</summary>

{% code overflow="wrap" %}

```bash
curl -G "http(s)://server_entry_point" \
  --data-urlencode 'cmd=style_guide' \
  --data-urlencode 'access_key=<your-access-key>' \
  --data-urlencode 'collection=style guide' \
  --data-urlencode 'lang=en_US' \
  --data-urlencode 'action=addrule' \
  --data-urlencode 'patterns=["webspellchecker"]' \
  --data-urlencode 'suggestions=["WebSpellChecker"]'
```

{% endcode %}

</details>

<details>

<summary>Request CURL (Cloud)</summary>

{% code overflow="wrap" %}

```bash
curl -G "https://svc.webspellchecker.net/api" \
  --data-urlencode 'cmd=style_guide' \
  --data-urlencode 'access_key=<your-access-key>' \
  --data-urlencode 'serviceid=<your-service-id>' \
  --data-urlencode 'collection=style guide' \
  --data-urlencode 'lang=en_US' \
  --data-urlencode 'action=addrule' \
  --data-urlencode 'patterns=["webspellchecker"]' \
  --data-urlencode 'suggestions=["WebSpellChecker"]'
```

{% endcode %}

</details>

***

<details>

<summary>Response</summary>

{% code overflow="wrap" %}

```json
{
    "message": "Rule added.",
    "result": [
        {
            "state": true,
            "language": "en_US",
            "id": {
                "category": "STYLE_GUIDE",
                "collection": "style guide",
                "rule": "STYLE_5933619761905272220"
            },
            "patterns": [
                "webspellchecker"
            ],
            "suggestions": [
                "WebSpellChecker"
            ],
            "description": "",
            "context_include": [],
            "context_exclude": []
        }
    ]
}
```

{% endcode %}

</details>
{% endtab %}

{% tab title="Example (XML body)" %}

<details>

<summary>Request URL (on-premises)</summary>

{% code overflow="wrap" %}

```
http(s)://server_entry_point/?cmd=style_guide&access_key=<your-access-key>&collection=style guide&lang=en_US&action=addrule&patterns=["webspellchecker"]&suggestions=["WebSpellChecker"]&format=xml
```

{% endcode %}

</details>

<details>

<summary>Request URL (Cloud)</summary>

{% code overflow="wrap" %}

```
https://svc.webspellchecker.net/api?cmd=style_guide&access_key=<your-access-key>&serviceid=<your-service-id>&collection=style guide&lang=en_US&action=addrule&patterns=["webspellchecker"]&suggestions=["WebSpellChecker"]&format=xml
```

{% endcode %}

</details>

<details>

<summary>Request CURL (on-premises)</summary>

{% code overflow="wrap" %}

```bash
curl -G "http(s)://server_entry_point" \
  --data-urlencode 'cmd=style_guide' \
  --data-urlencode 'access_key=<your-access-key>' \
  --data-urlencode 'collection=style guide' \
  --data-urlencode 'lang=en_US' \
  --data-urlencode 'action=addrule' \
  --data-urlencode 'patterns=["webspellchecker"]' \
  --data-urlencode 'suggestions=["WebSpellChecker"]' \
  --data-urlencode 'format=xml'
```

{% endcode %}

</details>

<details>

<summary>Request CURL (Cloud)</summary>

{% code overflow="wrap" %}

```bash
curl -G "https://svc.webspellchecker.net/api" \
  --data-urlencode 'cmd=style_guide' \
  --data-urlencode 'access_key=<your-access-key>' \
  --data-urlencode 'serviceid=<your-service-id>' \
  --data-urlencode 'collection=style guide' \
  --data-urlencode 'lang=en_US' \
  --data-urlencode 'action=addrule' \
  --data-urlencode 'patterns=["webspellchecker"]' \
  --data-urlencode 'suggestions=["WebSpellChecker"]' \
  --data-urlencode 'format=xml'
```

{% endcode %}

</details>

***

<details>

<summary>Response</summary>

{% code overflow="wrap" %}

```xml
<message>Rule added.</message>

<result>
	<rule>
		<state>true</state>
		<language>en_US</language>
		<id>
			<category>STYLE_GUIDE</category>
			<collection>style guide</collection>
			<rule>STYLE_5933619761905272220</rule>
		</id>
		<patterns>
			<patterns>webspellchecker</patterns>
		</patterns>
		<suggestions>
			<suggestions>WebSpellChecker</suggestions>
		</suggestions>
		<description/>
		<context_include/>
		<context_exclude/>
	</rule>
</result>
```

{% endcode %}

</details>
{% endtab %}
{% endtabs %}