# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wproofreader.com/api-reference/style-guide-api/response-schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.