Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Manage ingress and egress firewall rules for a computer. Use these endpoints to inspect the current rule set, add or remove rules, temporarily enable or disable rules, or reset the firewall to an open state.

In the Hub, open Computers, select a computer and open Network. Its Firewall section lists the rules: use Add a rule or Presets to add rules, Turn off or Turn on and Delete on a rule, or Reset to no rules to remove every rule. Internet access, on the same tab, blocks the computer’s outbound traffic with firewall rules.

The cURL examples use https://api.hoody.com and send the Hoody account token in the Authorization header. Replace {id} with the computer ID.

Returns all ingress and egress firewall rules for a computer, along with the current rule count, serialized size, and applicable limits.

NameInTypeRequiredDescription
idpathstringYesComputer ID.

This endpoint does not accept a request body.

FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
dataobjectFirewall rule data.
data.ingress[], data.egress[]arrayIngress and egress firewall rules.
data.ingress[].action, data.egress[].actionstringRule action. Allowed values: allow, reject, drop.
data.ingress[].protocol, data.egress[].protocolstringNetwork protocol. Allowed values: tcp, udp, icmp4.
data.ingress[].description, data.egress[].descriptionstringRule description.
data.ingress[].destination_port, data.egress[].destination_portstringDestination port, port range, or comma-separated port list.
data.ingress[].source, data.egress[].sourcestringSource IPv4 address or CIDR range.
data.ingress[].destination, data.egress[].destinationstringDestination IPv4 address or CIDR range.
data.ingress[].source_port, data.egress[].source_portstringSource port, port range, or comma-separated port list.
data.ingress[].state, data.egress[].statestringRule state. Allowed values: enabled, disabled. Default: "enabled".
data.ingress[].icmp_type, data.egress[].icmp_typestringICMP type number for icmp4 rules.
data.ingress[].icmp_code, data.egress[].icmp_codestringICMP code number for icmp4 rules.
data.ingress[].direction, data.egress[].directionstringRule direction. Allowed values: ingress, egress.
data.rule_countnumberCurrent number of ingress and egress rules. Advisory.
data.byte_countnumberSerialized size of the current rule set in bytes. Advisory.
data.max_rulesnumberMaximum number of ingress and egress rules allowed on the computer.
data.max_bytesnumberMaximum serialized size of the computer’s rule set in bytes.

Media type: application/json

{
"statusCode": 200,
"message": "Rules retrieved successfully",
"data": {
"ingress": [
{
"action": "allow",
"protocol": "tcp",
"description": "Allow HTTPS traffic",
"destination_port": "443",
"source": "0.0.0.0/0",
"state": "enabled"
},
{
"action": "allow",
"protocol": "icmp4",
"description": "Allow ping from any source",
"source": "0.0.0.0/0",
"state": "enabled",
"icmp_type": "8",
"icmp_code": "0"
}
],
"egress": [
{
"action": "allow",
"protocol": "tcp",
"description": "Allow outbound HTTPS",
"destination_port": "443",
"destination": "0.0.0.0/0",
"state": "enabled"
},
{
"action": "drop",
"protocol": "tcp",
"description": "Block outbound SMTP",
"destination_port": "25",
"destination": "0.0.0.0/0",
"state": "enabled"
}
]
}
}
Terminal window
curl --request GET \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/rules' \
--header "Authorization: Bearer $HOODY_TOKEN"

POST /api/v1/computers/{id}/firewall/ingress

Section titled “POST /api/v1/computers/{id}/firewall/ingress”

Adds an ingress rule to control traffic that can reach a computer. destination_port is required for tcp and udp rules and is not allowed with icmp4. A rule that already exists returns 200; a newly added rule returns 201.

NameInTypeRequiredDescription
idpathstringYesComputer ID.
NameTypeRequiredDescription
actionstringYesAction to take. Allowed values: allow, reject, drop.
protocolstringYesNetwork protocol. Allowed values: tcp, udp, icmp4.
descriptionstringYesHuman-readable rule description. Maximum length: 255 characters.
destination_portstringNoPort number from 1 through 65535, a low-to-high range, or a comma-separated list. Required for tcp and udp, and not allowed with icmp4. Maximum length: 64 characters.
sourcestringNoSource IPv4 address or CIDR range, or a comma-separated list. Use 0.0.0.0/0 for any source. IPv6 is not supported. Maximum length: 512 characters.
source_portstringNoSource port filter. Maximum length: 64 characters.
statestringNoRule state. Allowed values: enabled, disabled. Default: "enabled".
icmp_typestringNoICMP type number, such as 8 for an echo request. Maximum length: 8 characters.
icmp_codestringNoICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
warningsarrayWarnings about the added rule.
warnings[].codestringWarning code. Allowed value: FIREWALL_RULE_COVERS_KIT_PORTS.
warnings[].messagestringWarning message.
warnings[].portsarrayHoody kit ports covered by the rule.
dataobjectThe complete ingress and egress rule set, or duplicate rule details when the rule already exists.

Media type: application/json

{
"statusCode": 200,
"message": "Rule already exists (duplicate)",
"data": {
"action": "allow",
"protocol": "tcp",
"description": "Allow HTTPS traffic",
"destination_port": "443",
"source": "0.0.0.0/0",
"state": "enabled",
"duplicate": true,
"duplicate_of": {
"direction": "ingress",
"index": 0
}
}
}
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"action": "allow",
"protocol": "tcp",
"description": "Allow SSH from office",
"destination_port": "22",
"source": "203.0.113.5/32"
}'

POST /api/v1/computers/{id}/firewall/egress

Section titled “POST /api/v1/computers/{id}/firewall/egress”

Adds an egress rule to control traffic sent by a computer. destination_port is required for tcp and udp rules and is not allowed with icmp4. A rule that already exists returns 200; a newly added rule returns 201.

NameInTypeRequiredDescription
idpathstringYesComputer ID.
NameTypeRequiredDescription
actionstringYesAction to take. Allowed values: allow, reject, drop.
protocolstringYesNetwork protocol. Allowed values: tcp, udp, icmp4.
descriptionstringYesHuman-readable rule description. Maximum length: 255 characters.
destination_portstringNoPort number from 1 through 65535, a low-to-high range, or a comma-separated list. Required for tcp and udp, and not allowed with icmp4. Maximum length: 64 characters.
destinationstringNoDestination IPv4 address or CIDR range, or a comma-separated list. Use 0.0.0.0/0 for any destination. IPv6 is not supported. Maximum length: 512 characters.
source_portstringNoSource port filter. Maximum length: 64 characters.
statestringNoRule state. Allowed values: enabled, disabled. Default: "enabled".
icmp_typestringNoICMP type number. Maximum length: 8 characters.
icmp_codestringNoICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
dataobjectThe complete ingress and egress rule set, or duplicate rule details when the rule already exists.

Media type: application/json

{
"statusCode": 200,
"message": "Rule already exists (duplicate)",
"data": {
"action": "allow",
"protocol": "tcp",
"description": "Allow outbound HTTPS",
"destination_port": "443",
"destination": "0.0.0.0/0",
"state": "enabled",
"duplicate": true,
"duplicate_of": {
"direction": "egress",
"index": 0
}
}
}
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"action": "drop",
"protocol": "tcp",
"description": "Block outbound SMTP",
"destination_port": "25",
"destination": "0.0.0.0/0"
}'

PATCH /api/v1/computers/{id}/firewall/ingress

Section titled “PATCH /api/v1/computers/{id}/firewall/ingress”

Enables or disables an ingress rule without deleting it. Supply filters that identify the rule to update.

NameInTypeRequiredDescription
idpathstringYesComputer ID.
NameTypeRequiredDescription
statestringYesNew rule state. Allowed values: enabled, disabled. The TypeScript SDK methods set this value automatically.
actionstringNoMatch rules with this action. Allowed values: allow, reject, drop.
protocolstringNoMatch rules with this protocol. Allowed values: tcp, udp, icmp4.
destination_portstringNoMatch this destination port, range, or comma-separated list. Maximum length: 64 characters.
source_portstringNoMatch this source port, range, or comma-separated list. Maximum length: 64 characters.
sourcestringNoMatch this source IPv4 address or CIDR range. Maximum length: 512 characters.
descriptionstringNoMatch this rule description. Maximum length: 255 characters.
icmp_typestringNoMatch this ICMP type number. Maximum length: 8 characters.
icmp_codestringNoMatch this ICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
data.directionstringDirection of the updated rule.
data.new_statestringNew state of the rule.
data.updatedobjectUpdated rule.
data.updated.actionstringRule action. Allowed values: allow, reject, drop.
data.updated.protocolstringNetwork protocol. Allowed values: tcp, udp, icmp4.
data.updated.descriptionstringRule description.
data.updated.destination_portstringDestination port, range, or comma-separated list.
data.updated.sourcestringSource IPv4 address or CIDR range.
data.updated.source_portstringSource port, range, or comma-separated list.
data.updated.statestringRule state. Allowed values: enabled, disabled. Default: "enabled".
data.updated.icmp_typestringICMP type number.
data.updated.icmp_codestringICMP code number.

Media type: application/json

{
"statusCode": 200,
"message": "Ingress rule state toggled successfully",
"data": {
"direction": "ingress",
"new_state": "disabled",
"updated": {
"action": "allow",
"protocol": "tcp",
"description": "Allow HTTPS traffic",
"destination_port": "443",
"source": "0.0.0.0/0",
"state": "disabled"
}
}
}
Terminal window
curl --request PATCH \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"state": "enabled",
"action": "allow",
"protocol": "tcp",
"destination_port": "443",
"source": "203.0.113.5/32"
}'

PATCH /api/v1/computers/{id}/firewall/egress

Section titled “PATCH /api/v1/computers/{id}/firewall/egress”

Enables or disables an egress rule without deleting it. Supply filters that identify the rule to update.

NameInTypeRequiredDescription
idpathstringYesComputer ID.
NameTypeRequiredDescription
statestringYesNew rule state. Allowed values: enabled, disabled. The TypeScript SDK methods set this value automatically.
actionstringNoMatch rules with this action. Allowed values: allow, reject, drop.
protocolstringNoMatch rules with this protocol. Allowed values: tcp, udp, icmp4.
destination_portstringNoMatch this destination port, range, or comma-separated list. Maximum length: 64 characters.
source_portstringNoMatch this source port, range, or comma-separated list. Maximum length: 64 characters.
destinationstringNoMatch this destination IPv4 address or CIDR range. Maximum length: 512 characters.
descriptionstringNoMatch this rule description. Maximum length: 255 characters.
icmp_typestringNoMatch this ICMP type number. Maximum length: 8 characters.
icmp_codestringNoMatch this ICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
data.directionstringDirection of the updated rule.
data.new_statestringNew state of the rule.
data.updatedobjectUpdated rule.
data.updated.actionstringRule action. Allowed values: allow, reject, drop.
data.updated.protocolstringNetwork protocol. Allowed values: tcp, udp, icmp4.
data.updated.descriptionstringRule description.
data.updated.destination_portstringDestination port, range, or comma-separated list.
data.updated.destinationstringDestination IPv4 address or CIDR range.
data.updated.source_portstringSource port, range, or comma-separated list.
data.updated.statestringRule state. Allowed values: enabled, disabled. Default: "enabled".
data.updated.icmp_typestringICMP type number.
data.updated.icmp_codestringICMP code number.

Media type: application/json

{
"statusCode": 200,
"message": "Egress rule state toggled successfully",
"data": {
"direction": "egress",
"new_state": "enabled",
"updated": {
"action": "allow",
"protocol": "tcp",
"description": "Allow outbound HTTPS",
"destination_port": "443",
"destination": "0.0.0.0/0",
"state": "enabled"
}
}
}
Terminal window
curl --request PATCH \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"state": "enabled",
"action": "drop",
"protocol": "tcp",
"destination_port": "25",
"destination": "0.0.0.0/0"
}'

DELETE /api/v1/computers/{id}/firewall/ingress

Section titled “DELETE /api/v1/computers/{id}/firewall/ingress”

Removes one or more ingress rules. Supply filters that identify the rules to remove, or set all: true to remove all ingress rules. If state is omitted, rules in either state match. Removal filters do not require destination_port when protocol is tcp or udp. This operation does not reset the firewall.

NameInTypeRequiredDescription
idpathstringYesComputer ID.

The request body is required. Each field is optional, but the request must contain at least one filter or set all: true.

NameTypeRequiredDescription
allbooleanNoRemove all matching rules. By default, only the first match is removed. Set to true with no other filters to remove all ingress rules.
actionstringNoMatch rules with this action. Allowed values: allow, reject, drop.
protocolstringNoMatch rules with this protocol. Allowed values: tcp, udp, icmp4.
destination_portstringNoMatch this destination port, range, or comma-separated list. It is not required for removal filters that use tcp or udp. Maximum length: 64 characters.
sourcestringNoMatch this source IPv4 address or CIDR range. Maximum length: 512 characters.
source_portstringNoMatch this source port, range, or comma-separated list. Maximum length: 64 characters.
descriptionstringNoMatch this rule description. Maximum length: 255 characters.
statestringNoMatch only rules in this state. Allowed values: enabled, disabled. Omit to match rules in either state.
icmp_typestringNoMatch this ICMP type number. Maximum length: 8 characters.
icmp_codestringNoMatch this ICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
data.directionstringDirection of the removed rules.
data.removed_countnumberNumber of removed rules.
data.removed[]arrayRemoved ingress rules.
data.removed[].actionstringRule action. Allowed values: allow, reject, drop.
data.removed[].protocolstringNetwork protocol. Allowed values: tcp, udp, icmp4.
data.removed[].descriptionstringRule description.
data.removed[].destination_portstringDestination port, range, or comma-separated list.
data.removed[].sourcestringSource IPv4 address or CIDR range.
data.removed[].source_portstringSource port, range, or comma-separated list.
data.removed[].statestringRule state. Allowed values: enabled, disabled. Default: "enabled".
data.removed[].icmp_typestringICMP type number.
data.removed[].icmp_codestringICMP code number.

Media type: application/json

{
"statusCode": 200,
"message": "Ingress rule(s) removed successfully",
"data": {
"direction": "ingress",
"removed_count": 1,
"removed": [
{
"action": "allow",
"protocol": "tcp",
"description": "Allow SSH from office",
"destination_port": "22",
"source": "192.168.1.0/24",
"state": "enabled"
}
]
}
}
Terminal window
curl --request DELETE \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"protocol": "tcp",
"destination_port": "22",
"source": "203.0.113.5/32"
}'

DELETE /api/v1/computers/{id}/firewall/egress

Section titled “DELETE /api/v1/computers/{id}/firewall/egress”

Removes one or more egress rules. Supply filters that identify the rules to remove, or set all: true to remove all egress rules. If state is omitted, rules in either state match. Removal filters do not require destination_port when protocol is tcp or udp. This operation does not reset the firewall.

NameInTypeRequiredDescription
idpathstringYesComputer ID.

The request body is required. Each field is optional, but the request must contain at least one filter or set all: true.

NameTypeRequiredDescription
allbooleanNoRemove all matching rules. By default, only the first match is removed. Set to true with no other filters to remove all egress rules.
actionstringNoMatch rules with this action. Allowed values: allow, reject, drop.
protocolstringNoMatch rules with this protocol. Allowed values: tcp, udp, icmp4.
destination_portstringNoMatch this destination port, range, or comma-separated list. It is not required for removal filters that use tcp or udp. Maximum length: 64 characters.
destinationstringNoMatch this destination IPv4 address or CIDR range. Maximum length: 512 characters.
source_portstringNoMatch this source port, range, or comma-separated list. Maximum length: 64 characters.
descriptionstringNoMatch this rule description. Maximum length: 255 characters.
statestringNoMatch only rules in this state. Allowed values: enabled, disabled. Omit to match rules in either state.
icmp_typestringNoMatch this ICMP type number. Maximum length: 8 characters.
icmp_codestringNoMatch this ICMP code number. Maximum length: 8 characters.
FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
data.directionstringDirection of the removed rules.
data.removed_countnumberNumber of removed rules.
data.removed[]arrayRemoved egress rules.
data.removed[].actionstringRule action. Allowed values: allow, reject, drop.
data.removed[].protocolstringNetwork protocol. Allowed values: tcp, udp, icmp4.
data.removed[].descriptionstringRule description.
data.removed[].destination_portstringDestination port, range, or comma-separated list.
data.removed[].destinationstringDestination IPv4 address or CIDR range.
data.removed[].source_portstringSource port, range, or comma-separated list.
data.removed[].statestringRule state. Allowed values: enabled, disabled. Default: "enabled".
data.removed[].icmp_typestringICMP type number.
data.removed[].icmp_codestringICMP code number.

Media type: application/json

{
"statusCode": 200,
"message": "Egress rule(s) removed successfully",
"data": {
"direction": "egress",
"removed_count": 2,
"removed": [
{
"action": "allow",
"protocol": "tcp",
"description": "Allow outbound HTTPS",
"destination_port": "443",
"destination": "0.0.0.0/0",
"state": "enabled"
},
{
"action": "allow",
"protocol": "tcp",
"description": "Allow outbound DNS",
"destination_port": "53",
"destination": "8.8.8.8",
"state": "enabled"
}
]
}
}
Terminal window
curl --request DELETE \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"protocol": "tcp",
"destination_port": "25"
}'

POST /api/v1/computers/{id}/firewall/reset

Section titled “POST /api/v1/computers/{id}/firewall/reset”

Removes all firewall rules and returns the computer to an open state.

NameInTypeRequiredDescription
idpathstringYesComputer ID.

This endpoint does not accept a request body.

FieldTypeDescription
statusCodenumberHTTP status code.
messagestringResult message.
dataobjectReset result.
data.rulesobjectRules remaining after the reset.
data.rules.ingressarrayRemaining ingress rules.
data.rules.egressarrayRemaining egress rules.

Media type: application/json

{
"statusCode": 200,
"message": "Firewall reset successfully",
"data": {
"rules": {
"ingress": [],
"egress": []
}
}
}
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/computers/{id}/firewall/reset' \
--header "Authorization: Bearer $HOODY_TOKEN"