---
title: "Create instance"
method: POST
path: "/api/v2/instances"
tags: ["Instances"]
---

# Create instance

`POST /api/v2/instances`

Create an instance.

## Request body

- InstanceCreate — A compute instance creation 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` InstanceCreateSpec, required — A compute instance.
    - `flavorId` string, required — The flavor CPU/RAM of a compute instance.
    - `imageId` string, required — The image of a compute instance.
    - `networking` InstanceNetworking — A compute instance's network configuration.
      - `securityGroups` string[] — A list of security group IDs.
      - `publicIP` boolean — Whether or not to provision a public IP.
      - `allowedSourceAddresses` string[] — A list of network prefixes that are allowed to egress from the server. By default, only packets from the server's network interface's IP address are allowed to enter the network. Use of this option allows the server to act as a router without SNAT rules.
    - `userData` string, byte — Contains base64-encoded configuration information or scripts to use upon launch. The format of the data is governed by the cloud-init standard, and may be a script, a MIME multipart archive, etc.
    - `organizationId` string, required — The organization to provision the resource in.
    - `projectId` string, required — The project to provision the resource in.
    - `networkId` string, required — The network ID to attach the compute instance to.

## Response `201`

A compute instance.

- InstanceRead — A compute instance.
  - `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` InstanceSpec, required — A compute instance.
    - `flavorId` string, required — The flavor CPU/RAM of a compute instance.
    - `imageId` string, required — The image of a compute instance.
    - `networking` InstanceNetworking — A compute instance's network configuration.
      - `securityGroups` string[] — A list of security group IDs.
      - `publicIP` boolean — Whether or not to provision a public IP.
      - `allowedSourceAddresses` string[] — A list of network prefixes that are allowed to egress from the server. By default, only packets from the server's network interface's IP address are allowed to enter the network. Use of this option allows the server to act as a router without SNAT rules.
    - `userData` string, byte — Contains base64-encoded configuration information or scripts to use upon launch. The format of the data is governed by the cloud-init standard, and may be a script, a MIME multipart archive, etc.
  - `status` InstanceStatus, required — Read only status information about a compute instance.
    - `regionId` string, required — The region a security group belongs to.
    - `networkId` string, required — The network a security group belongs to.
    - `powerState` 'Pending' | 'Queued' | 'Building' | 'Running' | 'Stopping' | 'Stopped' — The lifecycle phase of an instance. Once provisioning_status reaches provisioned, this becomes the live readiness signal: API consumers should treat Running (not provisioned) as the "ready to use" state. Queued and Building are observed during create — Queued for baremetal servers waiting on hardware, Building for servers the provider is actively bringing up.
    - `privateIP` string — The private IP address of the server.
    - `publicIP` string — The public IP address of the server.

## 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.
- `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)