Skip to content

List VPS firewall rules

GET /api/v2/vps/{id}/firewall

Get the VPS firewall: whether it filters incoming traffic, its rules and how many more you can add. Use a rule’s pos as {pos} to change or delete it. Positions shift after every add or delete. Read the list again before the next change. Only rules with editable: true can be changed. Through the API those are the inbound (type: "in") rules. Outbound rules and group references are read-only here. available: false means the state could not be read or a stored rule needs repair by support. reason then says why and changes are blocked. actions.canAddRule and actions.canToggleFirewall say whether you can add a rule or switch the firewall on or off now.

Authentication: An API key with the scope read:vm. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

GET /api/v2/vps/{id}/firewall
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/firewall" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Firewall state and rules.

Response 200
{
"available": true,
"reason": null,
"enabled": true,
"summary": "Firewall protection is on. Incoming traffic must match an allow rule to pass.",
"detail": "Traffic that does not match one of the rules below is blocked on our side before it reaches the VM.",
"limits": {
"maxRules": 100,
"currentRules": 1,
"remainingRules": 99
},
"rules": [
{
"pos": 0,
"type": "in",
"action": "ACCEPT",
"enabled": true,
"proto": "tcp",
"dport": "22",
"sport": null,
"source": "198.51.100.10",
"dest": null,
"description": "Allow SSH from office",
"isSystem": false,
"editable": true
}
],
"ruleCount": 1,
"actions": {
"canAddRule": {
"allowed": true,
"reason": null
},
"canToggleFirewall": {
"allowed": true,
"reason": null
}
}
}
Response fields
availableboolean
Whether the firewall can be read and changed. False when the state could not be read or a stored rule needs repair by support.
reasonstring or null
Why the firewall is unavailable. Null when it is available.
enabledboolean
True when the firewall filters incoming traffic. Traffic then needs a matching allow rule. Same value as platformFilteringInbound on GET /api/v2/vps/{id}/firewall/options, not its enabled. Also false when the state could not be read. Check available first.
summarystring or null
The state in one sentence.
detailstring or null
What the state means for incoming traffic.
limitsobject
maxRulesinteger
Most rules a VPS can have.
currentRulesinteger
Rules the VPS has now.
remainingRulesinteger
Rules you can still add.
rulesarray of object
The rules in list order.
posinteger or null
Position in the rule list. The first rule is 0.
typestring or null
in: an inbound rule you can change. out (outbound) and group (a group reference) are read-only. One of in, out, group.
actionstring or null
ACCEPT lets matching traffic through. DROP discards it. REJECT refuses it. One of ACCEPT, DROP, REJECT.
enabledboolean
Whether the rule is switched on.
protostring or null
Protocol, for example tcp, udp or icmp. Null for all protocols.
dportstring or null
Port on the VPS: a port, a range such as 8000:8100 or a comma-separated list. Null for all ports.
sportstring or null
Port on the sender’s side. Null for any. It does not open a port on the VPS.
sourcestring or null
Sender address or CIDR. Null for any sender.
deststring or null
Destination address or CIDR. Null for any.
descriptionstring or null
Your label for the rule.
isSystemboolean
True for a group reference.
editableboolean
Whether you can change or delete the rule through the API.
ruleCountinteger
Number of rules.
actionsobject
canAddRuleobject
Whether a rule can be added now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canToggleFirewallobject
Whether the firewall can be switched on or off now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.