# Rules

A rule is a policy used to manage access control traffic on your network and devices. Each rule either blocks, allows, or time limits traffic matching a certain target and a certain device or set of devices. Rules can also have custom schedules. The targets for the rules can be applications, target lists, network flow information (IPs, domains, ports), Internet access, local networks, or activity categories (gaming, adult, video, etc.).

## Get Rules

Gets all rules with given conditions.

[!badge variant="primary" text="GET"] <span style="color:grey">https://msp_domain</span>**/v2/rules**

<p class="parameters">Parameters</p>
<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Query String</p>

| Name  | Value                                                                |
| ----- | -------------------------------------------------------------------- |
| query | The search query. See [Query basics](./search.md#rule-qualifiers) |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>

</p>

| Name      | Type                                   | Description                                                        |
| --------- | -------------------------------------- | ------------------------------------------------------------------ |
| `count`   | Number                                 | Number of results in the response                                  |
| `results` | [Rule](../data-models/rule.md/#rule)[] | List of rules being returned, it returns all matched rules for now |

```json
{
  "count": 1,
  "results": [
      {
            "id": "00000000-0000-0000-0000-000000000001",
            "action": "allow",
            "direction": "bidirection",
            "gid": "00000000-0000-0000-0000-000000000000",
            "notes": "",
            "status": "active",
            "ts": 1730447709.791,
            "target": {
                "type": "domain",
                "value": "firewalla.com",
                "dnsOnly": true
            },
            "scope": {
                "type": "device",
                "value": "AA:BB:CC:DD:EE:FF"
            }
        }
  ]
}

```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";

axios({
    method: "get",
    url: `https://${msp_domain}/v2/rules?query=box.id:${gid}`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request GET  \
--url "https://${msp_domain}/v2/rules?query=box.id:00000000-0000-0000-0000-000000000000" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Create A Rule
This API creates a new rule. Currently, only `block` and `allow` rules are supported.

[!badge variant="primary" text="POST"] <span style="color:grey">https://msp_domain</span>**/v2/rules**

<p class="parameters">Parameters</p>
<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |
| Content-Type <span style="color:orange">*required*</span> | application/json      |

<p class="header">Body</p>

A [Rule](../data-models/rule.md/#rule) without `id`, `ts`, `updateTs`, and `resumeTs`. The `action` field must be either `block` or `allow`.

```json
{
    "action": "block",
    "direction": "bidirection",
    "gid": "00000000-0000-0000-0000-000000000000",
    "notes": "Block example.com",
    "target": {
        "type": "domain",
        "value": "example.com",
        "dnsOnly": true
    },
    "scope": {
        "type": "device",
        "value": "AA:BB:CC:DD:EE:FF"
    }
}
```

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

A JSON representation of [Rule](../data-models/rule.md/#rule)

```json
{
    "id": "00000000-0000-0000-0000-000000000001",
    "action": "block",
    "direction": "bidirection",
    "gid": "00000000-0000-0000-0000-000000000000",
    "notes": "Block example.com",
    "status": "active",
    "ts": 1730447709.791,
    "target": {
        "type": "domain",
        "value": "example.com",
        "dnsOnly": true
    },
    "scope": {
        "type": "device",
        "value": "AA:BB:CC:DD:EE:FF"
    }
}
```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>400 Bad Request</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";

const rule = {
    "action": "block",
    "direction": "bidirection",
    "gid": gid,
    "notes": "Block example.com",
    "target": {
        "type": "domain",
        "value": "example.com",
        "dnsOnly": true
    },
    "scope": {
        "type": "device",
        "value": "AA:BB:CC:DD:EE:FF"
    }
};

axios({
    method: "post",
    url: `https://${msp_domain}/v2/rules`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: rule
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request POST  \
--url "https://${msp_domain}/v2/rules" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{
    "action": "block",
    "direction": "bidirection",
    "gid": "00000000-0000-0000-0000-000000000000",
    "notes": "Block example.com",
    "target": {
        "type": "domain",
        "value": "example.com",
        "dnsOnly": true
    },
    "scope": {
        "type": "device",
        "value": "AA:BB:CC:DD:EE:FF"
    }
}'
```
+++

## Pause A Rule
This API pauses an existing rule. The Rule ID can be found by navigating to the Rules page in MSP, clicking a rule, then scrolling to the bottom of the dialog.

[!badge variant="primary" text="POST"] <span style="color:grey">https://msp_domain</span>**/v2/rules/:id/pause**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                            | Value   |
| ----------------------------------------------- | ------- |
| id <span style="color:orange">*required*</span> | Rule ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

- [Pause An Existing Rule](https://github.com/firewalla/msp-api-examples/tree/main/pause-an-existing-rule)

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const id = 1;

axios({
    method: "post",
    url: `https://${msp_domain}/v2/rules/${id}/pause`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request POST  \
--url "https://${msp_domain}/v2/rules/${id}/pause" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Resume A Rule
This API resumes an existing rule. The Rule ID can be found by navigating to the Rules page in MSP, clicking a rule, then scrolling to the bottom of the dialog.

[!badge variant="primary" text="POST"] <span style="color:grey">https://msp_domain</span>**/v2/rules/:id/resume**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                            | Value   |
| ----------------------------------------------- | ------- |
| id <span style="color:orange">*required*</span> | Rule ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const id = 1;

axios({
    method: "post",
    url: `https://${msp_domain}/v2/rules/${id}/resume`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request POST  \
--url "https://${msp_domain}/v2/rules/${id}/resume" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Delete A Rule [!badge variant="warning" text="MSP 2.11.0 or later"]
This API deletes an existing rule. The Rule ID can be found by navigating to the Rules page in MSP, clicking a rule, then scrolling to the bottom of the dialog.

[!badge variant="danger" text="DELETE"] <span style="color:grey">https://msp_domain</span>**/v2/rules/:id**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                            | Value   |
| ----------------------------------------------- | ------- |
| id <span style="color:orange">*required*</span> | Rule ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const id = "00000000-0000-0000-0000-000000000001";

axios({
    method: "delete",
    url: `https://${msp_domain}/v2/rules/${id}`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request DELETE  \
--url "https://${msp_domain}/v2/rules/${id}" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++