Field Reference

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

The Terraform provider’s nirvana_networking_vpc attribute names are identical to the JSON field names below.

Create a VPC

POST /v1/networking/vpcs

Field	Type	Required	Allowed values / limits
name	string	Yes	e.g. my-vpc
project_id	string	Yes	Project UUID
region	string	Yes	us-sva-2
subnet_name	string	Yes	Name for the subnet created alongside the VPC, e.g. my-subnet
tags	array of strings	No	Maximum 50 entries

A VPC is always created with exactly one subnet, and subnet_name is required because of it. You do not supply a CIDR — the subnet’s CIDR is assigned by the platform and returned in the response.

Example request

curl -sS https://api.nirvanalabs.io/v1/networking/vpcs \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
  -d '{
        "name": "my-vpc",
        "project_id": "123e4567-e89b-12d3-a456-426614174000",
        "region": "us-sva-2",
        "subnet_name": "my-subnet",
        "tags": ["production"]
      }'

Update a VPC

PATCH /v1/networking/vpcs/{vpc_id}

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

Field	Type	Allowed values / limits
name	string	New name
subnet_name	string	New subnet name
tags	array of strings	Maximum 50 entries. Replaces the existing list

region and project_id are not updatable.

VPC Response Fields

Returned by GET /v1/networking/vpcs/{vpc_id} and in GET /v1/networking/vpcs items. All of these are always present.

Field	Type	Notes
id	string	VPC UUID
name	string
project_id	string
region	string	us-sva-2
status	string	See Status values
subnet	object	See Subnet
firewall_rule_ids	array of strings	IDs of the firewall rules attached to this VPC
tags	array of strings
created_at	string	RFC 3339 timestamp
updated_at	string	RFC 3339 timestamp

Subnet

Field	Type	Notes
id	string	Subnet UUID. This is the value to pass as a VM’s subnet_id
name	string
cidr	string	Assigned by the platform, e.g. 10.128.35.128/25
created_at	string	RFC 3339 timestamp
updated_at	string	RFC 3339 timestamp

Two fields here are what you need for everything downstream: subnet.id is the subnet_id a VM requires, and subnet.cidr is the usual destination_address for a firewall rule covering the whole VPC.

List VPCs

GET /v1/networking/vpcs

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

project_id is a required query parameter — a request without it fails with 400, it does not fall back to a default project.

Status Values

status on a VPC is one of:

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

The status list filter accepts all of these except deleted.

Writes Return an Operation

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

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

This matters when chaining calls: a VM needs subnet.id, which is only readable once the VPC operation completes. Creating a VM immediately after posting the VPC will fail because the subnet does not exist yet.

Error Responses

Handle 400, 403, 404, 409, and 500 on create.

Note

The OpenAPI specification lists only 403, 404, 409 and 500 for VPC create, but 400 does occur: the handler binds and validates the request body before doing anything else, and either step rejects a malformed body or an invalid field with a validation error. The omission is a gap in the endpoint’s annotation, not a guarantee — a client written to treat 400 as impossible here will mishandle ordinary validation failures.

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

Related

• Create a VPC
• Firewall Rule Field Reference
• VM Field Reference