### Rule

| Name | Type | Description |
|------|------|-------------|
| `id` | String | Unique identifier of this rule |
| `name` | String <span style="color:gray">*optional*</span> | Human-readable name of this rule |
| `action` | String | Rule action, possible values: `allow` `block` `timelimit`, defaults to `block` |
| `target` | [Target](#target) | The target of this rule |
| `direction` | String | Direction of the traffic this rule applies to. Possible values: `bidirection` `inbound` `outbound`, defaults to `bidirection` |
| `gid` | String <span style="color:gray">*optional*</span> | ID of the Firewalla box that this rule applies to |
| `group` | String <span style="color:gray">*optional*</span> | ID of the Firewalla box group that this rule applies to, defaults to `global`. If neither `gid` nor `group` is provided, this rule applies to all boxes under current MSP, including boxes added in the future |
| `scope` | [Scope](#scope) <span style="color:gray">*optional*</span> | The local aspect this rule applies to, unset for all devices |
| `notes` | String <span style="color:gray">*optional*</span> | Readable notes for this rule |
| `status` | String <span style="color:gray">*optional*</span> | Status of this rule, possible values: `active` `paused` |
| `hit` | [Hit](#hit) <span style="color:gray">*optional*</span> | Rule hit stats [!badge variant="warning" text="Upcoming"] |
| `schedule` | [Schedule](#schedule) <span style="color:gray">*optional*</span> | Schedule of this rule, unset for always active |
| `timeUsage` | [Time Usage](#time-usage) <span style="color:gray">*optional*</span> | Details of time limit rules.<br>Available when `action == 'timelimit'` |
| `protocol` | String <span style="color:gray">*optional*</span> | Protocol of the traffic, matches together with [Target](#target) and [Scope](#scope) when set. Possible values: `tcp` `udp`, unset for both. |
| `ts` | Number | A Unix timestamp that states the rule creation time |
| `updateTs` | Number | A Unix timestamp that states the last rule update time |
| `resumeTs` | Number <span style="color:gray">*optional*</span> | A Unix timestamp that states the auto resume time when this rule is paused<br>Available when `status == 'paused'` |

### Target

| Name | Type | Description |
|------|------|-------------|
| `type` | String | Type of target this rule matches, possible values: `app` `category` `domain` `internet` `intranet` `ip` `net` `region` `remotePort` `targetlist` |
| `value` | String | Target descriptor, see [Target Type And Value Mapping](#target-type-and-value-mapping) |
| `dnsOnly` | Boolean <span style="color:gray">*optional*</span> | Option flag indicates whether this rule uses only DNS to block. For domain rules, Firewalla uses both DNS and domain-IP mapping to identify traffic. If this flag is set, this rule applies only to DNS traffic.<br>Available when `type in ['category', 'app', 'targetlist', 'domain']`. Defaults to `true` when creating block rules with these target types. |
| `port` | String <span style="color:gray">*optional*</span> | Port number or a range of ports of the target, matches together with target descriptor when set.<br>Available when `type in ['domain', 'ip', 'net']` |

### Scope

| Name | Type | Description |
|------|------|-------------|
| `type` | String | Scope type this rule applies to, possible values: `device` `group` `user` `network` |
| `value` | String | Scope descriptor, see [Scope Type And Value Mapping](#scope-type-and-value-mapping) |
| `port` | String <span style="color:gray">*optional*</span> | Port number or a range of ports of scope, matches together with scope descriptor when set. |

### Hit

| Name | Type | Description |
|------|------|-------------|
| `count` | Number | Number of hits |
| `lastHitTs` | Number | Timestamp of the last hit |
| `statsResetTs` | Number <span style="color:gray">*optional*</span> | Timestamp of the hit info reset |

### Schedule

| Name | Type | Description |
|------|------|-------------|
| `duration` | Number | Time (in seconds) that this rule takes effect after activation time. This affects both one time rule and recurring rule, must present when cronTime is set |
| `cronTime` | String <span style="color:gray">*optional*</span> | Activation time of this rule, in format of a cron job. For details, check the date and time section of [cron manual](https://manpages.ubuntu.com/manpages/jammy/man5/crontab.5.html) |

### Time Usage

| Name | Type | Description |
|------|------|-------------|
| `quota` | Number | Time usage quota (in minutes) |
| `used` | Number | Time used (in minutes) |

### Target Type And Value Mapping

| `type` | `value` | Description |
|--------|---------|-------------|
| `app` | app id | Application ID. The API for getting the app list is coming soon.<br>Available values: `discord` `facebook` `fortnite` `instagram` `netflix` `roblox` `snapchat` `tiktok` `twitch` `twitter` `youtube` |
| `category` | category code | Category code. <br>Possible values `drugs` `games` `gamble` `p2p` `porn` `social` `shopping` `video` `violence` `vpn` |
| `domain` | domain name | Domain name <br>e.g., `example.com` |
| `internet` | always unset | The Internet in most scenarios, but this actually matches all traffic routed through the WAN port(s) of Firewalla |
| `intranet` | unset or network ID | A part or all of Firewalla's local network, which matches all traffic that isn't routed through WAN port(s). This can be set to a Network ID to match a specific local network or unset for all local networks |
| `ip` | ip address | IP address <br>e.g., `192.168.0.1` |
| `net` | network address | Network address in CIDR notation<br>e.g., `192.168.0.0/24` |
| `region` | region code | Region code, a 2-letter [ISO 3166 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) <br>e.g., `US` |
| `remotePort` | port number or a range of ports | Port number or a range of ports<br> e.g.,`443` or `440-443` |
| `targetlist` | targetlist id | Targetlist identifier [Target-List](../target-lists) |

### Scope Type And Value Mapping

| `type` | `value` | Description |
|--------|---------|-------------|
| `device` | device ID | Device identifier [Device](../device) |
| `group` | group ID | Group identifier |
| `user` | user ID | User identifier |
| `network` | network ID | Network identifier |