Skip to content
Nirvana Labs Docs
Directory SDKs APISign In

Field Reference

This page lists the exact field names, types, and allowed values for firewall rules, so a request can be built without trial and error. Everything here is taken from the OpenAPI specification.

The Terraform provider’s nirvana_networking_firewall_rule attribute names are identical to the JSON field names below, plus a vpc_id attribute that stands in for the path parameter.

Create a Firewall Rule

Section titled “Create a Firewall Rule”

POST /v1/networking/vpcs/{vpc_id}/firewall_rules

Firewall rules are nested under a VPC: vpc_id is a path parameter, not a body field.

Parameter In Type Required
vpc_id path string Yes

Body fields:

Field Type Required Allowed values / limits
name string Yes e.g. my-firewall-rule
protocol string Yes tcp or udp
source_address string Yes CIDR, e.g. 0.0.0.0/0. Must be in network-aligned (canonical) form
destination_address string Yes CIDR, e.g. 10.0.0.0/25. Either the VPC CIDR or a VM in the VPC. Must be in network-aligned (canonical) form
destination_ports array of strings Yes e.g. ["22", "80", "443"]
tags array of strings No Maximum 50 entries

Two constraints on the address fields are easy to trip over:

  • Network-aligned CIDR only. The address must be the network address for its mask. 10.0.0.0/25 is accepted; 10.0.0.5/25 is not, because 10.0.0.5 is not the start of a /25 block.
  • 0.0.0.0 requires a /0 mask. Write 0.0.0.0/0 to mean “any address”.

There is no direction, action, priority, or source_ports field. A rule describes allowed traffic from source_address to destination_address on destination_ports; rules are stateless.

Example request

Section titled “Example request”
Terminal window
curl -sS https://api.nirvanalabs.io/v1/networking/vpcs/123e4567-e89b-12d3-a456-426614174000/firewall_rules \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
  -d '{
        "name": "allow-ssh",
        "protocol": "tcp",
        "source_address": "0.0.0.0/0",
        "destination_address": "10.128.35.128/25",
        "destination_ports": ["22"],
        "tags": ["production"]
      }'

The usual value for destination_address is the VPC’s own subnet CIDR, which you read from the VPC’s subnet.cidr field.

Update a Firewall Rule

Section titled “Update a Firewall Rule”

PATCH /v1/networking/vpcs/{vpc_id}/firewall_rules/{firewall_rule_id}

Every field is optional; send only what you are changing.

Field Type Allowed values / limits
name string New name
protocol string tcp or udp
source_address string Network-aligned CIDR
destination_address string Network-aligned CIDR
destination_ports array of strings Replaces the existing list
tags array of strings Maximum 50 entries. Replaces the existing list

Firewall Rule Response Fields

Section titled “Firewall Rule Response Fields”
Field Type Notes
id string Firewall rule UUID
name string
vpc_id string VPC the rule belongs to
protocol string tcp or udp
source_address string
destination_address string
destination_ports array of strings
status string See Status values
tags array of strings
created_at string RFC 3339 timestamp
updated_at string RFC 3339 timestamp

List Firewall Rules

Section titled “List Firewall Rules”

GET /v1/networking/vpcs/{vpc_id}/firewall_rules

Parameter In Type Required Allowed values / default
vpc_id path string Yes VPC UUID
limit query integer No 10–100, default 10
cursor query string No Cursor from a previous response. Only valid for the same VPC, filters, and sort order
status query string No pending, creating, updating, ready, deleting, error
protocol query string No tcp or udp
tags query array No Repeat the parameter to require several tags; a rule must carry all of them
name query string No Case-insensitive substring match
sort query string No Comma-separated field:asc/field:desc in precedence order. Fields: created_at, updated_at, name, status, protocol. Default created_at:desc

Unlike the VM and VPC list endpoints, this one takes no project_id — the vpc_id path parameter already scopes the results.

Status Values

Section titled “Status Values”

status on a firewall rule is one of:

pending, creating, updating, ready, deleting, deleted, error

The status list filter accepts all of these except deleted.

Writes Return an Operation

Section titled “Writes Return an Operation”

Create, update, and delete return 202 Accepted with an Operation — not the firewall rule. Poll GET /v1/operations/{operation_id} with the returned id until status is done or failed, then read the rule by resource_id.

Field Type Notes
id string Operation UUID
resource_id string UUID of the firewall rule being acted on
kind string firewall_rule for these endpoints
type string create, update, delete, restart
status string pending, running, done, failed, unknown

Error Responses

Section titled “Error Responses”

Create returns 400, 403, 404, 409, or 500. The specification documents which statuses each endpoint can return but not which condition maps to which status, so treat the type and message fields in the body as the reliable signal rather than inferring a cause from the status code.

All errors share one shape:

{
  "type": "VALIDATION_ERROR",
  "message": "invalid id format",
  "context": { "parameters": {} },
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2025-01-01T00:00:00Z"
}
Field Type Notes
type string Machine-readable error category
message string Human-readable description
context.parameters object Which parameters were at fault, when applicable
request_id string Quote this when contacting support
timestamp string RFC 3339 timestamp
Section titled “Related”