> 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/api-reference/style-guide-api/response-schema.md).

# Response schema

This API returns a consistent success envelope.

### Success

The success response always has these top-level fields:

| Field              | Type    | Notes                                                                                                                                                            |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`          | string  | Human-readable result of the action.                                                                                                                             |
| `result`           | array   | <p>Always an array of objects. Can contain:<br>- multiple rules items<br>- multiple collection items</p><p>- be empty.</p>                                       |
| `collection_limit` | integer | Present only for collection actions. The effective maximum number of collections for this service ID. See [Collection action fields](#collection-action-fields). |
| `collection_usage` | integer | Present only for collection actions. The current total collection count for this service ID. See [Collection action fields](#collection-action-fields).          |

#### Rule item response example:

{% tabs %}
{% tab title="JSON" %}

```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": "The company name should be spelled in the mixed case.",
      "context_include": [],
      "context_exclude": []
    }
  ]
}
```

{% endtab %}

{% tab title="XML" %}

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

<result>
  <rule>
    <state>true</state>
    <language>en_US</language>
    <id>
      <category>STYLE_GUIDE</category>
      <rule>STYLE_5933619761905272220</rule>
    </id>
    <patterns>
      <patterns>webspellchecker</patterns>
    </patterns>
    <suggestions>
      <suggestions>WebSpellChecker</suggestions>
    </suggestions>
    <description>The company name should be spelled in the mixed case.</description>
    <context_include/>
    <context_exclude/>
  </rule>
</result>
```

{% endtab %}
{% endtabs %}

#### Collection item response example:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "message": "Collection added.",
  "collection_limit": 250,
  "collection_usage": 1,
  "result": [
    {
      "language": "en_US",
      "collection": "My really-new collection",
      "category": "MY_REALLY-NEW_COLLECTION"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

#### Notes

* `result` is always an array.
* The array can contain:\
  \- one or more rule objects\
  \- one or more collection objects

### Success messages

The `message` value depends on `action`.

| Action                      | Message                  |
| --------------------------- | ------------------------ |
| `addrule`                   | Rule added.              |
| `editrule`                  | Rule updated.            |
| `deleterule`, `deleterules` | Rule(s) deleted.         |
| `getrules`                  | Rules retrieved.         |
| `addcollection`             | Collection added.        |
| `deletecollection`          | Collection deleted.      |
| `editcollection`            | Collection updated.      |
| `getcollections`            | Collection(s) retrieved. |

### Rule object

`language` is the rule language scope.

It matches the request `lang` value (`common`, `en`, `en_US`, etc).

#### Fields

| Field             | Type (JSON)      | Notes                                                      |
| ----------------- | ---------------- | ---------------------------------------------------------- |
| `id`              | object           | Rule identifier.                                           |
| `id.category`     | string           | Category name / namespace.                                 |
| `id.rule`         | string           | Unique rule ID.                                            |
| `state`           | boolean          | `true` means enabled.                                      |
| `language`        | string           | Same scope as request `lang` (`common`, `en`, `en_US`, …). |
| `patterns`        | array of strings | Patterns to match.                                         |
| `suggestions`     | array of strings | Replacement suggestions. Can be empty.                     |
| `description`     | string           | Optional explanatory message.                              |
| `context_include` | array of strings | Additional context required for match. Can be empty.       |
| `context_exclude` | array of strings | Context that blocks a match. Can be empty.                 |

### Collection object

`language` is the collection language scope.

It matches the request `lang` value (`common`, `en`, `en_US`, etc).

#### Fields

| Field        | Type (JSON) | Notes                                                      |
| ------------ | ----------- | ---------------------------------------------------------- |
| `language`   | string      | Same scope as request `lang` (`common`, `en`, `en_US`, …). |
| `collection` | string      | Provided collection name with request parameter.           |
| `category`   | string      | Category name / namespace created from `collection` value. |

### Collection action fields

For `addcollection`, `deletecollection`, `editcollection`, and `getcollections`, the response includes two additional top-level fields alongside `message` and `result`:

| Field              | Type    | Description                                                                                                                |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `collection_limit` | integer | The effective maximum number of collections allowed for this service ID.                                                   |
| `collection_usage` | integer | The current total collection count for this service ID. Always reflects the full count, regardless of any filters applied. |

These fields are **not** present in rule actions (`addrule`, `editrule`, `deleterule`, `getrules`).

### Errors

Errors use the standard HTTP API error format.

See [HTTP API Overview](/api-reference/overview.md#errors).