Container Firewall

Manage ingress and egress firewall rules for a container. Use these endpoints to inspect existing rules, add new rules, toggle rule state without deletion, remove rules, or fully reset the firewall back to an open state.

All operations are scoped to a single container identified by {id}. Rules support three actions (allow, reject, drop) over tcp, udp, and icmp4 protocols, with optional filters for source, destination, ports, ICMP fields, and an enabled/disabled state.

Note

All endpoints use the base URL https://api.hoody.com. Authentication is performed by passing a JWT in the Authorization: Bearer <token> header.

List firewall rules

GET /api/v1/containers/{id}/firewall/rules

Get all ingress and egress firewall rules for a container, along with rule and byte counts and the applicable limits for this container.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

cURL

curl -X GET "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/rules" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const { data } = await client.api.firewall.list({ id: "c_abc123def456" });
const { ingress, egress } = data;

200 Response

{
  "statusCode": 200,
  "message": "Firewall 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"
      }
    ],
    "rule_count": 4,
    "byte_count": 412,
    "max_rules": 500,
    "max_bytes": 262144
  }
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
CONTAINER_NOT_FOUND	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

Add firewall rule

Add an ingress or egress rule. All rules default to state: "enabled" when not specified.

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

Add a new ingress (inbound) firewall rule to control which traffic can reach the container.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Description
action	string	Yes	Action for matching traffic: allow, reject, or drop
protocol	string	Yes	Network protocol: tcp, udp, or icmp4
description	string	Yes	Human-readable rule description (max 255 chars)
destination_port	string	No	Port number, range (e.g. 80-90), or comma-separated list (e.g. 80,443). Required for tcp/udp
source	string	No	Source IPv4 address or CIDR range. Use 0.0.0.0/0 for any source
source_port	string	No	Source port filter (rarely used)
state	string	No	Rule state: enabled or disabled. Defaults to enabled
icmp_type	string	No	ICMP type number (e.g. 8 for echo request/ping)
icmp_code	string	No	ICMP code number

cURL

curl -X POST "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/ingress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow HTTPS",
    "destination_port": "443",
    "source": "0.0.0.0/0"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.addIngressRule("c_abc123def456", {
  action: "allow",
  protocol: "tcp",
  description: "Allow HTTPS",
  destination_port: "443",
  source: "0.0.0.0/0"
});

201 Response

{
  "statusCode": 201,
  "message": "Ingress rule added successfully",
  "data": {}
}

200

{
  "statusCode": 200,
  "message": "Rule already exists",
  "data": {}
}

400

{
  "statusCode": 400,
  "error": "CONTAINER_FIREWALL_RULE_LIMIT",
  "message": "This container has reached its firewall rule limit.",
  "data": {
    "field": "container_firewall_rule_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 500,
    "limit": 500
  }
}

Error Code	Title	Description	Resolution
CONTAINER_FIREWALL_RULE_LIMIT	Container firewall rule limit reached	The container already holds the maximum number of firewall rules allowed (ingress and egress counted together). The applicable limit is returned as max_rules when listing firewall rules.	Remove an existing firewall rule on this container before adding a new one.
CONTAINER_FIREWALL_BYTES_LIMIT	Container firewall rule size limit reached	The container’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large (long descriptions or address lists). The applicable limit is returned as max_bytes when listing firewall rules.	Remove rules, or shorten descriptions and address lists, before adding a new rule.

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

503

{
  "statusCode": 503,
  "error": "FIREWALL_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's firewall rules. No changes were made.",
  "data": {
    "field": "firewall_inventory",
    "container_id": "507f1f77bcf86cd799439011"
  }
}

Error Code	Title	Description	Resolution
FIREWALL_INVENTORY_UNAVAILABLE	Firewall inventory unavailable	The container’s live firewall rule list could not be established (host unreachable, or a malformed response), so the rule limit could not be evaluated. The request fails closed: no rule was added.	Retry shortly. If it persists, the hosting server may be unreachable.

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

Add a new egress (outbound) firewall rule to control which traffic the container can send.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Description
action	string	Yes	Action for matching traffic: allow, reject, or drop
protocol	string	Yes	Network protocol: tcp, udp, or icmp4
description	string	Yes	Human-readable rule description (max 255 chars)
destination_port	string	No	Port number, range (e.g. 80-90), or comma-separated list (e.g. 80,443). Required for tcp/udp
destination	string	No	Destination IPv4 address or CIDR range. Use 0.0.0.0/0 for any destination
source_port	string	No	Source port filter (rarely used)
state	string	No	Rule state: enabled or disabled. Defaults to enabled
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

cURL

curl -X POST "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/egress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow outbound HTTPS",
    "destination_port": "443",
    "destination": "0.0.0.0/0"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.addEgressRule("c_abc123def456", {
  action: "allow",
  protocol: "tcp",
  description: "Allow outbound HTTPS",
  destination_port: "443",
  destination: "0.0.0.0/0"
});

201 Response

{
  "statusCode": 201,
  "message": "Egress rule added successfully",
  "data": {}
}

200

{
  "statusCode": 200,
  "message": "Rule already exists",
  "data": {}
}

400

{
  "statusCode": 400,
  "error": "CONTAINER_FIREWALL_RULE_LIMIT",
  "message": "This container has reached its firewall rule limit.",
  "data": {
    "field": "container_firewall_rule_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 500,
    "limit": 500
  }
}

Error Code	Title	Description	Resolution
CONTAINER_FIREWALL_RULE_LIMIT	Container firewall rule limit reached	The container already holds the maximum number of firewall rules allowed (ingress and egress counted together). The applicable limit is returned as max_rules when listing firewall rules.	Remove an existing firewall rule on this container before adding a new one.
CONTAINER_FIREWALL_BYTES_LIMIT	Container firewall rule size limit reached	The container’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large (long descriptions or address lists). The applicable limit is returned as max_bytes when listing firewall rules.	Remove rules, or shorten descriptions and address lists, before adding a new rule.

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

503

{
  "statusCode": 503,
  "error": "FIREWALL_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's firewall rules. No changes were made.",
  "data": {
    "field": "firewall_inventory",
    "container_id": "507f1f77bcf86cd799439011"
  }
}

Error Code	Title	Description	Resolution
FIREWALL_INVENTORY_UNAVAILABLE	Firewall inventory unavailable	The container’s live firewall rule list could not be established (host unreachable, or a malformed response), so the rule limit could not be evaluated. The request fails closed: no rule was added.	Retry shortly. If it persists, the hosting server may be unreachable.

Toggle firewall rule state

Enable or disable an existing rule without deleting it. Provide the rule’s identifying fields plus a new state.

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

Toggle the state of an ingress (inbound) firewall rule.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Description
state	string	Yes	New state for the rule: enabled or disabled
action	string	No	Action for matching traffic: allow, reject, or drop
protocol	string	No	Network protocol: tcp, udp, or icmp4
destination_port	string	No	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
source	string	No	Source IPv4 address or CIDR range
source_port	string	No	Source port, range, or list
description	string	No	Rule description
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

cURL

curl -X PATCH "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/ingress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "disabled",
    "protocol": "tcp",
    "destination_port": "443"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.toggleIngressRule("c_abc123def456", {
  state: "disabled",
  protocol: "tcp",
  destination_port: "443"
});

200 Response

{
  "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"
    }
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

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

Toggle the state of an egress (outbound) firewall rule.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Description
state	string	Yes	New state for the rule: enabled or disabled
action	string	No	Action for matching traffic: allow, reject, or drop
protocol	string	No	Network protocol: tcp, udp, or icmp4
destination_port	string	No	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
source_port	string	No	Source port, range, or list
destination	string	No	Destination IPv4 address or CIDR range
description	string	No	Rule description
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

cURL

curl -X PATCH "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/egress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "disabled",
    "protocol": "tcp",
    "destination_port": "25"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.toggleEgressRule("c_abc123def456", {
  state: "disabled",
  protocol: "tcp",
  destination_port: "25"
});

200 Response

{
  "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"
    }
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Remove firewall rule

Remove one or more rules that match the supplied filters. Pass all: true to remove every rule on the requested side, or combine all with other filters to bulk-remove a subset.

Caution

This deletes rules but leaves the firewall ACL and bridge attachment in place. Use POST /firewall/reset to detach the firewall entirely.

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

Remove ingress (inbound) firewall rules matching the supplied filters.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Default	Description
all	boolean	No	—	Remove all matching rules. Set to true with no other filters to remove all ingress rules
action	string	No	—	Action for matching traffic: allow, reject, or drop
protocol	string	No	—	Network protocol: tcp, udp, or icmp4
destination_port	string	No	—	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
source	string	No	—	Source IPv4 address or CIDR range
source_port	string	No	—	Source port, range, or list
description	string	No	—	Rule description
state	string	No	"enabled"	Rule state: enabled or disabled
icmp_type	string	No	—	ICMP type number
icmp_code	string	No	—	ICMP code number

cURL

curl -X DELETE "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/ingress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "tcp",
    "destination_port": "22",
    "source": "192.168.1.0/24"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.removeIngressRule("c_abc123def456", {
  protocol: "tcp",
  destination_port: "22",
  source: "192.168.1.0/24"
});

200 Response

{
  "statusCode": 200,
  "message": "Ingress rule 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"
      }
    ]
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

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

Remove egress (outbound) firewall rules matching the supplied filters.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Name	Type	Required	Default	Description
all	boolean	No	—	Remove all matching rules. Set to true with no other filters to remove all egress rules
action	string	No	—	Action for matching traffic: allow, reject, or drop
protocol	string	No	—	Network protocol: tcp, udp, or icmp4
destination_port	string	No	—	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
destination	string	No	—	Destination IPv4 address or CIDR range
source_port	string	No	—	Source port, range, or list
description	string	No	—	Rule description
state	string	No	"enabled"	Rule state: enabled or disabled
icmp_type	string	No	—	ICMP type number
icmp_code	string	No	—	ICMP code number

cURL

curl -X DELETE "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/egress" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "all": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.removeEgressRule("c_abc123def456", { all: true });

200 Response

{
  "statusCode": 200,
  "message": "Egress rules 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"
      }
    ]
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Reset firewall

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

Delete the firewall ACL and detach the container from its firewall bridge, returning the container to an open (unfiltered) state. This is destructive: every ingress and egress rule is removed and the firewall attachment is torn down.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

This endpoint takes no parameters beyond the path parameter and accepts no request body.

cURL

curl -X POST "https://api.hoody.com/api/v1/containers/c_abc123def456/firewall/reset" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.reset("c_abc123def456");

200 Response

{
  "statusCode": 200,
  "message": "Firewall reset successfully",
  "data": {
    "rules": {
      "ingress": [],
      "egress": []
    }
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}