Firewalls API

All endpoints require a bearer token (a login JWT or an API key).

A firewall is a plain IP allow-list. Each rule is an IP or CIDR plus a description - that is the whole model. There are no ports, protocols, or directions. Only source addresses on the list can reach the pod; everyone else is blocked. Firewalls attach to a pod from the pod side (at pod creation or the pod's Networking tab).

The firewall object

{
  "id": "fw_abc123",
  "name": "allow-my-ips",
  "rules": [
    { "cidr": "203.0.113.42/32", "description": "Home IP" },
    { "cidr": "198.51.100.0/24", "description": "Office range" }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}

A rule has exactly two fields:

Field	Type	Notes
cidr	string	An IP (203.0.113.42) or CIDR (198.51.100.0/24).
description	string	Free text, truncated to 255 characters.

List firewalls

GET /api/firewalls?page=1&limit=20

Paginated list of your firewalls.

Create a firewall

POST /api/firewalls

{
  "name": "allow-my-ips",
  "rules": [
    { "cidr": "203.0.113.42/32", "description": "Home IP" }
  ]
}

Rules follow a few rules of their own:

• At least one rule is required (400 "At least one firewall rule is required").
• At most 15 rules per firewall (400 "A maximum of 15 firewall rules are allowed per firewall").
• 0.0.0.0/0 (allow everyone) is stored as 0.0.0.0.
• Duplicate CIDRs are silently dropped.
• name is optional (we generate one if blank) and unique within your account.

Creating a firewall needs at least $3 of account credit like any other create (402 otherwise). Firewalls themselves are free.

Describe a firewall

GET /api/firewalls/:id

Firewall stats

GET /api/firewalls/:id/stats

{
  "blocked": 1840,
  "allowed": 502100,
  "activeSessions": 12,
  "bytesIn": 44210000,
  "bytesOut": 981200000,
  "portCount": 3
}

blocked is the number of connections the allow-list rejected. portCount is how many public ports the firewall currently guards (one per pod service it fronts) - it does not mean rules have ports. Values are cumulative.

Update a firewall

PUT /api/firewalls/:id

{
  "name": "allow-my-ips",
  "rules": [
    { "cidr": "203.0.113.42/32", "description": "Home IP" },
    { "cidr": "198.51.100.0/24", "description": "Office range" }
  ]
}

The rules array replaces the existing rules, but only when you send a non-empty array. Omit rules (or send an empty array) and the existing rules are left untouched - handy when you only want to rename. Changes take effect within seconds, no reboot needed.

Delete a firewall

DELETE /api/firewalls/:id

Returns 204. If a pod is still using the firewall it returns 400 "Firewall is in use by existing pods" - detach it from the pod first.