---
title: "Create network"
method: POST
path: "/api/v2/networks"
tags: ["Networks"]
---

# Create network

`POST /api/v2/networks`

Create a new network.

## Request body

- NetworkV2Create — A network request.
  - `metadata` ResourceMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
  - `spec` NetworkV2CreateSpec, required — A network's specification.
    - `dnsNameservers` Ipv4Address[], required — A list of IPv4 addresses.
    - `routes` Route[] — A list of network routes.
      - `prefix` string, required — An IPv4 prefix for the route.
      - `nexthop` string, required — An IPv4 address for the route's next hop.
    - `organizationId` string, required — The organization to provision the resource in.
    - `projectId` string, required — The project to provision the resource in.
    - `regionId` string, uuid, required — A region ID.
    - `prefix` string, required — An IPv4 prefix for the network. Dynamic modification of the network prefix is not supported at this time, and doing so would involve adding a route between discrete broadcast domains so ensure this is large enough for your potential requirements during the life time of your infrastructure.
    - `reservations` NetworkReservations — Network reservations carve a prefix from the start of the network CIDR for infrastructure use such as file storage and internal platform services as directed by the infrastructure provider. For example, on a /24 network a reservation prefix length of 25 reserves 192.168.0.0/25, leaving 192.168.0.128-192.168.0.254 for DHCP. Reservations are fixed when the network is created and are immutable afterwards.
      - `prefixLength` integer, required — Defines how much of the network to reserve, starting at the beginning of the network CIDR. For example, on a /24 network a value of 25 reserves the lower half of the network, i.e. 192.168.0.0/25. The network address (.0) and gateway (.1) are platform-reserved within that space, so usable reserved addresses begin at .2. The reservation prefix length must be greater than the network prefix length.
      - `providerReservedPrefixLength` integer — Optionally carves a prefix from the start of the reserved space for provider use. For example, on a /24 network with prefixLength=25 and providerReservedPrefixLength=28, 192.168.0.0/28 is reserved for provider use and storage uses the remainder of the reserved space, 192.168.0.16-192.168.0.127. If this matches prefixLength, the full reservation is treated as provider-reserved space and no storage range is left.

## Response `201`

A layer 3 network.

- NetworkV2Read — A network.
  - `metadata` ProjectScopedResourceReadMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
    - `id` string, required — The unique resource ID.
    - `creationTime` string, date-time, required — The time the resource was created.
    - `createdBy` string — The user who created the resource.
    - `modifiedTime` string, date-time — The time a resource was updated.
    - `modifiedBy` string — The user who updated the resource.
    - `deletionTime` string, date-time — The time the resource was deleted.
    - `provisioningStatus` 'unknown' | 'provisioning' | 'provisioned' | 'deprovisioning' | 'error', required — The provisioning state of a resource.
    - `healthStatus` 'unknown' | 'healthy' | 'degraded' | 'error', required — The health state of a resource.
    - `organizationId` string, required — The organization identifier the resource belongs to.
    - `projectId` string, required — The project identifier the resource belongs to.
  - `spec` NetworkV2Spec, required — A network's specification.
    - `dnsNameservers` Ipv4Address[], required — A list of IPv4 addresses.
    - `routes` Route[] — A list of network routes.
      - `prefix` string, required — An IPv4 prefix for the route.
      - `nexthop` string, required — An IPv4 address for the route's next hop.
  - `status` NetworkV2Status, required — Read only status about a network.
    - `regionId` string, required — The region a network is provisioned in.
    - `prefix` string, required — An IPv4 prefix for the network.
    - `reservations` NetworkReservations — Network reservations carve a prefix from the start of the network CIDR for infrastructure use such as file storage and internal platform services as directed by the infrastructure provider. For example, on a /24 network a reservation prefix length of 25 reserves 192.168.0.0/25, leaving 192.168.0.128-192.168.0.254 for DHCP. Reservations are fixed when the network is created and are immutable afterwards.
      - `prefixLength` integer, required — Defines how much of the network to reserve, starting at the beginning of the network CIDR. For example, on a /24 network a value of 25 reserves the lower half of the network, i.e. 192.168.0.0/25. The network address (.0) and gateway (.1) are platform-reserved within that space, so usable reserved addresses begin at .2. The reservation prefix length must be greater than the network prefix length.
      - `providerReservedPrefixLength` integer — Optionally carves a prefix from the start of the reserved space for provider use. For example, on a /24 network with prefixLength=25 and providerReservedPrefixLength=28, 192.168.0.0/28 is reserved for provider use and storage uses the remainder of the reserved space, 192.168.0.16-192.168.0.127. If this matches prefixLength, the full reservation is treated as provider-reserved space and no storage range is left.

## Other responses

- `400` — Request body failed schema validation, or the request does not contain all the required fields.
- `401` — Authentication failed or the access token has expired.
- `403` — Request was denied by authorization, this may be caused by the authorization token not having the required scope for an API, or the user doesn't have the necessary privileges on the provider platform.
- `404` — Unable to find a resource.
- `422` — The provided request was syntactically correct but the instruction was unable to be processed due to semantic errors.
- `500` — An unexpected or unhandled error occurred. This may be a transient error and may succeed on a retry. If this isn't the case, please report it as an issue.

---

[API](https://skmtc.net/nscale/apis/region-service-api.md) · [All operations](https://skmtc.net/nscale/apis/region-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nscale/region-service-api/revisions/c2991b23da6e/schema)