Computer Firewall
Section titled “Computer Firewall”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.
GET /api/v1/computers/{id}/firewall/rules
Section titled “GET /api/v1/computers/{id}/firewall/rules”Returns all ingress and egress firewall rules for a computer, along with the current rule count, serialized size, and applicable limits.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request
Section titled “Request”This endpoint does not accept a request body.
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data | object | Firewall rule data. |
data.ingress[], data.egress[] | array | Ingress and egress firewall rules. |
data.ingress[].action, data.egress[].action | string | Rule action. Allowed values: allow, reject, drop. |
data.ingress[].protocol, data.egress[].protocol | string | Network protocol. Allowed values: tcp, udp, icmp4. |
data.ingress[].description, data.egress[].description | string | Rule description. |
data.ingress[].destination_port, data.egress[].destination_port | string | Destination port, port range, or comma-separated port list. |
data.ingress[].source, data.egress[].source | string | Source IPv4 address or CIDR range. |
data.ingress[].destination, data.egress[].destination | string | Destination IPv4 address or CIDR range. |
data.ingress[].source_port, data.egress[].source_port | string | Source port, port range, or comma-separated port list. |
data.ingress[].state, data.egress[].state | string | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
data.ingress[].icmp_type, data.egress[].icmp_type | string | ICMP type number for icmp4 rules. |
data.ingress[].icmp_code, data.egress[].icmp_code | string | ICMP code number for icmp4 rules. |
data.ingress[].direction, data.egress[].direction | string | Rule direction. Allowed values: ingress, egress. |
data.rule_count | number | Current number of ingress and egress rules. Advisory. |
data.byte_count | number | Serialized size of the current rule set in bytes. Advisory. |
data.max_rules | number | Maximum number of ingress and egress rules allowed on the computer. |
data.max_bytes | number | Maximum 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" } ] }}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must be string", "data": [ { "instancePath": "/id", "schemaPath": "#/properties/id/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall rules could not be read. Nothing was changed.
The body contains statusCode, error, and message.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to retrieve firewall rules"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall rules could not be read. Nothing was changed. | Retry. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be read right now. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
curl --request GET \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/rules' \ --header "Authorization: Bearer $HOODY_TOKEN"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.listRules("c_abc123def456");console.log(data.ingress);console.log(data.egress);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Action to take. Allowed values: allow, reject, drop. |
protocol | string | Yes | Network protocol. Allowed values: tcp, udp, icmp4. |
description | string | Yes | Human-readable rule description. Maximum length: 255 characters. |
destination_port | string | No | Port 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. |
source | string | No | Source 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_port | string | No | Source port filter. Maximum length: 64 characters. |
state | string | No | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
icmp_type | string | No | ICMP type number, such as 8 for an echo request. Maximum length: 8 characters. |
icmp_code | string | No | ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
warnings | array | Warnings about the added rule. |
warnings[].code | string | Warning code. Allowed value: FIREWALL_RULE_COVERS_KIT_PORTS. |
warnings[].message | string | Warning message. |
warnings[].ports | array | Hoody kit ports covered by the rule. |
data | object | The 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 } }}Media type: application/json
{ "statusCode": 201, "message": "Ingress rule added successfully", "data": { "ingress": [ { "action": "allow", "protocol": "tcp", "description": "Allow HTTPS traffic", "destination_port": "443", "source": "0.0.0.0/0", "state": "enabled" } ], "egress": [] }}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 400, "error": "INVALID_RULE_DEFINITION", "message": "Invalid firewall rule definition."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_RULE_DEFINITION | Invalid Firewall Rule | The firewall rule definition is invalid: a field required by the protocol is missing, such as destination_port for TCP or UDP; a field is not allowed with the protocol, such as ports with icmp4 or icmp_type with TCP or UDP; or a value is malformed. data.field names the field. The rule was not added or changed. | Correct the field named in data.field. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. |
COMPUTER_FIREWALL_RULE_LIMIT | Computer firewall rule limit reached | The computer already holds the maximum number of firewall rules allowed, with ingress and egress counted together. The applicable limit is returned as max_rules when listing firewall rules. | Remove an existing firewall rule on this computer before adding a new one. |
COMPUTER_FIREWALL_BYTES_LIMIT | Computer firewall rule size limit reached | The computer’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large, such as rules with 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. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /action must be string", "data": [ { "instancePath": "/action", "schemaPath": "#/properties/action/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to add ingress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's firewall rules. No changes were made.", "data": { "field": "firewall_inventory", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_INVENTORY_UNAVAILABLE | Firewall inventory unavailable | The computer’s current firewall rules could not be read, so the rule limit could not be checked. No rule was added. | Retry shortly. If it persists, the hosting server may be unreachable. |
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.ingress.create("c_abc123def456", { action: "allow", protocol: "tcp", description: "Allow SSH from office", destination_port: "22", source: "203.0.113.5/32",});console.log(response);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Action to take. Allowed values: allow, reject, drop. |
protocol | string | Yes | Network protocol. Allowed values: tcp, udp, icmp4. |
description | string | Yes | Human-readable rule description. Maximum length: 255 characters. |
destination_port | string | No | Port 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. |
destination | string | No | Destination 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_port | string | No | Source port filter. Maximum length: 64 characters. |
state | string | No | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
icmp_type | string | No | ICMP type number. Maximum length: 8 characters. |
icmp_code | string | No | ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data | object | The 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 } }}Media type: application/json
{ "statusCode": 201, "message": "Egress rule added successfully", "data": { "ingress": [], "egress": [ { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled" } ] }}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 400, "error": "INVALID_RULE_DEFINITION", "message": "Invalid firewall rule definition."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_RULE_DEFINITION | Invalid Firewall Rule | The firewall rule definition is invalid: a field required by the protocol is missing, such as destination_port for TCP or UDP; a field is not allowed with the protocol, such as ports with icmp4 or icmp_type with TCP or UDP; or a value is malformed. data.field names the field. The rule was not added or changed. | Correct the field named in data.field. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. |
COMPUTER_FIREWALL_RULE_LIMIT | Computer firewall rule limit reached | The computer already holds the maximum number of firewall rules allowed, with ingress and egress counted together. The applicable limit is returned as max_rules when listing firewall rules. | Remove an existing firewall rule on this computer before adding a new one. |
COMPUTER_FIREWALL_BYTES_LIMIT | Computer firewall rule size limit reached | The computer’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large, such as rules with 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. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /action must be string", "data": [ { "instancePath": "/action", "schemaPath": "#/properties/action/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to add egress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's firewall rules. No changes were made.", "data": { "field": "firewall_inventory", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_INVENTORY_UNAVAILABLE | Firewall inventory unavailable | The computer’s current firewall rules could not be read, so the rule limit could not be checked. No rule was added. | Retry shortly. If it persists, the hosting server may be unreachable. |
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.egress.create("c_abc123def456", { action: "drop", protocol: "tcp", description: "Block outbound SMTP", destination_port: "25", destination: "0.0.0.0/0",});console.log(response);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
state | string | Yes | New rule state. Allowed values: enabled, disabled. The TypeScript SDK methods set this value automatically. |
action | string | No | Match rules with this action. Allowed values: allow, reject, drop. |
protocol | string | No | Match rules with this protocol. Allowed values: tcp, udp, icmp4. |
destination_port | string | No | Match this destination port, range, or comma-separated list. Maximum length: 64 characters. |
source_port | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. |
source | string | No | Match this source IPv4 address or CIDR range. Maximum length: 512 characters. |
description | string | No | Match this rule description. Maximum length: 255 characters. |
icmp_type | string | No | Match this ICMP type number. Maximum length: 8 characters. |
icmp_code | string | No | Match this ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data.direction | string | Direction of the updated rule. |
data.new_state | string | New state of the rule. |
data.updated | object | Updated rule. |
data.updated.action | string | Rule action. Allowed values: allow, reject, drop. |
data.updated.protocol | string | Network protocol. Allowed values: tcp, udp, icmp4. |
data.updated.description | string | Rule description. |
data.updated.destination_port | string | Destination port, range, or comma-separated list. |
data.updated.source | string | Source IPv4 address or CIDR range. |
data.updated.source_port | string | Source port, range, or comma-separated list. |
data.updated.state | string | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
data.updated.icmp_type | string | ICMP type number. |
data.updated.icmp_code | string | ICMP 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" } }}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /state must be string", "data": [ { "instancePath": "/state", "schemaPath": "#/properties/state/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to toggle ingress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.ingress.enable("c_abc123def456", { action: "allow", protocol: "tcp", destination_port: "443", source: "203.0.113.5/32",});console.log(response);The SDK state methods are:
client.api.firewall.ingress.enable(id, data)setsstate: "enabled".client.api.firewall.ingress.disable(id, data)setsstate: "disabled".
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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
state | string | Yes | New rule state. Allowed values: enabled, disabled. The TypeScript SDK methods set this value automatically. |
action | string | No | Match rules with this action. Allowed values: allow, reject, drop. |
protocol | string | No | Match rules with this protocol. Allowed values: tcp, udp, icmp4. |
destination_port | string | No | Match this destination port, range, or comma-separated list. Maximum length: 64 characters. |
source_port | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. |
destination | string | No | Match this destination IPv4 address or CIDR range. Maximum length: 512 characters. |
description | string | No | Match this rule description. Maximum length: 255 characters. |
icmp_type | string | No | Match this ICMP type number. Maximum length: 8 characters. |
icmp_code | string | No | Match this ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data.direction | string | Direction of the updated rule. |
data.new_state | string | New state of the rule. |
data.updated | object | Updated rule. |
data.updated.action | string | Rule action. Allowed values: allow, reject, drop. |
data.updated.protocol | string | Network protocol. Allowed values: tcp, udp, icmp4. |
data.updated.description | string | Rule description. |
data.updated.destination_port | string | Destination port, range, or comma-separated list. |
data.updated.destination | string | Destination IPv4 address or CIDR range. |
data.updated.source_port | string | Source port, range, or comma-separated list. |
data.updated.state | string | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
data.updated.icmp_type | string | ICMP type number. |
data.updated.icmp_code | string | ICMP 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" } }}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /state must be string", "data": [ { "instancePath": "/state", "schemaPath": "#/properties/state/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to toggle egress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.egress.enable("c_abc123def456", { action: "drop", protocol: "tcp", destination_port: "25", destination: "0.0.0.0/0",});console.log(response);The SDK state methods are:
client.api.firewall.egress.enable(id, data)setsstate: "enabled".client.api.firewall.egress.disable(id, data)setsstate: "disabled".
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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”The request body is required. Each field is optional, but the request must contain at least one filter or set all: true.
| Name | Type | Required | Description |
|---|---|---|---|
all | boolean | No | Remove all matching rules. By default, only the first match is removed. Set to true with no other filters to remove all ingress rules. |
action | string | No | Match rules with this action. Allowed values: allow, reject, drop. |
protocol | string | No | Match rules with this protocol. Allowed values: tcp, udp, icmp4. |
destination_port | string | No | Match this destination port, range, or comma-separated list. It is not required for removal filters that use tcp or udp. Maximum length: 64 characters. |
source | string | No | Match this source IPv4 address or CIDR range. Maximum length: 512 characters. |
source_port | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. |
description | string | No | Match this rule description. Maximum length: 255 characters. |
state | string | No | Match only rules in this state. Allowed values: enabled, disabled. Omit to match rules in either state. |
icmp_type | string | No | Match this ICMP type number. Maximum length: 8 characters. |
icmp_code | string | No | Match this ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data.direction | string | Direction of the removed rules. |
data.removed_count | number | Number of removed rules. |
data.removed[] | array | Removed ingress rules. |
data.removed[].action | string | Rule action. Allowed values: allow, reject, drop. |
data.removed[].protocol | string | Network protocol. Allowed values: tcp, udp, icmp4. |
data.removed[].description | string | Rule description. |
data.removed[].destination_port | string | Destination port, range, or comma-separated list. |
data.removed[].source | string | Source IPv4 address or CIDR range. |
data.removed[].source_port | string | Source port, range, or comma-separated list. |
data.removed[].state | string | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
data.removed[].icmp_type | string | ICMP type number. |
data.removed[].icmp_code | string | ICMP 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" } ] }}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 400, "error": "FIREWALL_UNKNOWN_FILTER", "message": "Unrecognised firewall filter(s)."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_UNKNOWN_FILTER | Unrecognised Firewall Filter | A remove request carried a filter this direction does not have, such as a misspelled name or a field that belongs to the other direction. destination belongs to egress and source belongs to ingress. An unrecognised filter would be ignored, which combined with all: true would remove every rule in the direction. data.unknown_filters lists the names. Nothing was removed. | Correct or drop the names listed in data.unknown_filters and send the request again. |
INVALID_RULE_DEFINITION | Invalid Firewall Rule | A filter value is malformed: a port outside 1-65535, a range whose first port is not lower, ports with a protocol other than tcp or udp, or an address that is not IPv4 or IPv4 CIDR. data.field names the field. Nothing was removed. | Correct the field named in data.field. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 422, "error": "FIREWALL_FILTER_REQUIRED", "message": "Give at least one filter (for example protocol and destination_port) to choose the rule to remove, or set \"all\": true to remove every rule in this direction.", "data": { "field": "firewall_filter" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_FILTER_REQUIRED | Firewall rule filter required | A remove request named no rule: it carried no filter with a value and did not set all: true. Nothing was removed. | Send at least one filter, such as protocol and destination_port, or all: true to remove every rule in the direction. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to remove ingress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.ingress.delete("c_abc123def456", { protocol: "tcp", destination_port: "22", source: "203.0.113.5/32",});console.log(response);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”The request body is required. Each field is optional, but the request must contain at least one filter or set all: true.
| Name | Type | Required | Description |
|---|---|---|---|
all | boolean | No | Remove all matching rules. By default, only the first match is removed. Set to true with no other filters to remove all egress rules. |
action | string | No | Match rules with this action. Allowed values: allow, reject, drop. |
protocol | string | No | Match rules with this protocol. Allowed values: tcp, udp, icmp4. |
destination_port | string | No | Match this destination port, range, or comma-separated list. It is not required for removal filters that use tcp or udp. Maximum length: 64 characters. |
destination | string | No | Match this destination IPv4 address or CIDR range. Maximum length: 512 characters. |
source_port | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. |
description | string | No | Match this rule description. Maximum length: 255 characters. |
state | string | No | Match only rules in this state. Allowed values: enabled, disabled. Omit to match rules in either state. |
icmp_type | string | No | Match this ICMP type number. Maximum length: 8 characters. |
icmp_code | string | No | Match this ICMP code number. Maximum length: 8 characters. |
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data.direction | string | Direction of the removed rules. |
data.removed_count | number | Number of removed rules. |
data.removed[] | array | Removed egress rules. |
data.removed[].action | string | Rule action. Allowed values: allow, reject, drop. |
data.removed[].protocol | string | Network protocol. Allowed values: tcp, udp, icmp4. |
data.removed[].description | string | Rule description. |
data.removed[].destination_port | string | Destination port, range, or comma-separated list. |
data.removed[].destination | string | Destination IPv4 address or CIDR range. |
data.removed[].source_port | string | Source port, range, or comma-separated list. |
data.removed[].state | string | Rule state. Allowed values: enabled, disabled. Default: "enabled". |
data.removed[].icmp_type | string | ICMP type number. |
data.removed[].icmp_code | string | ICMP 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" } ] }}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 400, "error": "FIREWALL_UNKNOWN_FILTER", "message": "Unrecognised firewall filter(s)."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_UNKNOWN_FILTER | Unrecognised Firewall Filter | A remove request carried a filter this direction does not have, such as a misspelled name or a field that belongs to the other direction. destination belongs to egress and source belongs to ingress. An unrecognised filter would be ignored, which combined with all: true would remove every rule in the direction. data.unknown_filters lists the names. Nothing was removed. | Correct or drop the names listed in data.unknown_filters and send the request again. |
INVALID_RULE_DEFINITION | Invalid Firewall Rule | A filter value is malformed: a port outside 1-65535, a range whose first port is not lower, ports with a protocol other than tcp or udp, or an address that is not IPv4 or IPv4 CIDR. data.field names the field. Nothing was removed. | Correct the field named in data.field. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 422, "error": "FIREWALL_FILTER_REQUIRED", "message": "Give at least one filter (for example protocol and destination_port) to choose the rule to remove, or set \"all\": true to remove every rule in this direction.", "data": { "field": "firewall_filter" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_FILTER_REQUIRED | Firewall rule filter required | A remove request named no rule: it carried no filter with a value and did not set all: true. Nothing was removed. | Send at least one filter, such as protocol and destination_port, or all: true to remove every rule in the direction. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to remove egress firewall rule"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.egress.delete("c_abc123def456", { protocol: "tcp", destination_port: "25",});console.log(response);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request
Section titled “Request”This endpoint does not accept a request body.
Responses
Section titled “Responses”Successful response fields
Section titled “Successful response fields”| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code. |
message | string | Result message. |
data | object | Reset result. |
data.rules | object | Rules remaining after the reset. |
data.rules.ingress | array | Remaining ingress rules. |
data.rules.egress | array | Remaining egress rules. |
Media type: application/json
{ "statusCode": 200, "message": "Firewall reset successfully", "data": { "rules": { "ingress": [], "egress": [] } }}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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. |
TOKEN_EXPIRED | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | The password is correct, but the account’s email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_quarantined | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The computer or its project does not exist. A computer you do not have access to is refused with 403.
The body contains statusCode, error, and message.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}Media type: application/json
The body contains statusCode, error, message, and data.
{ "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
OPERATION_STATE_CONFLICT | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
Media type: application/json
The body contains statusCode, error, message, and data. For a schema failure, each data entry contains instancePath, schemaPath, keyword, params, and message.
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must be string", "data": [ { "instancePath": "/id", "schemaPath": "#/properties/id/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ]}Media type: application/json
The body contains statusCode, error, and message.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
The Retry-After header contains the number of seconds to wait before retrying.
Media type: application/json
The firewall change failed unexpectedly. It may or may not have been applied.
The body contains statusCode, error, message, and data, where data is any JSON value.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to reset firewall"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. |
Media type: application/json
The firewall could not be reached for a moment. Nothing was changed. Retry after the Retry-After header.
The body contains statusCode, error, message, and data.
{ "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
FIREWALL_HOST_UNAVAILABLE | Firewall temporarily unavailable | The computer’s firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the Retry-After header. |
curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/reset' \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const response = await client.api.firewall.reset("c_abc123def456");console.log(response);