---
title: "Create an Instance"
method: POST
path: "/v2/org/{org}/nico/instance"
tags: ["Instance"]
---

# Create an Instance

`POST /v2/org/{org}/nico/instance`

Create an Instance for Tenant.

Org must have a Tenant entity. User must have authorization role with `TENANT_ADMIN` suffix.

## Request body

- InstanceCreateRequest — Request data to create Instance
  - `name` string, required — Name of the Instance
  - `description` string, nullable — Description of the Instance, optional
  - `tenantId` string, uuid, required — ID of the Tenant creating the Instance
  - `instanceTypeId` string, uuid, nullable — ID of the Instance Type to use for Instance
  - `machineId` string, nullable — ID of of specific Machine to use for Instance. Requires Targeted Instance Creation capability enabled for Tenant
  - `vpcId` string, uuid, required — ID of the VPC the Instance should belong to
  - `secondaryVpcIds` string[] — IDs of additional VPCs the Instance should attach to through non-primary interfaces. This field may only be specified when every entry in `interfaces` uses `vpcPrefixId`. IDs must be unique, must be valid UUIDs, and must not include the primary `vpcId`.
  - `userData` string, nullable — Can only be specified if allowOverride is set to true in Operating System
  - `operatingSystemId` string, uuid, nullable — Must be specified if iPXE Script field is empty
  - `networkSecurityGroupId` string, nullable
  - `ipxeScript` string, nullable — Override iPXE script specified in OS, must be specified if Operating System is not specified
  - `alwaysBootWithCustomIpxe` boolean — When set to true, the iPXE script specified by OS or overridden here will always be run when rebooting the Instance. OS must be of iPXE type.
  - `phoneHomeEnabled` boolean — When set to true, the Instance will be enabled with the Phone Home service.
  - `labels` Labels
  - `interfaces` InterfaceCreateRequest[] — At least one interface must be specified unless `autoNetwork` is true. Either Subnet or VPC Prefix interfaces allowed. Only one of the Subnets or VPC Prefixes can be attached over Physical interface. If only one Subnet is specified, then it will be attached over physical interface regardless of the value of isPhysical. In case of VPC Prefix, isPhysical will always be true. Mutually exclusive with `autoNetwork`: when `autoNetwork` is true this list MUST be empty.
    - `subnetId` string, uuid
    - `vpcPrefixId` string, uuid
    - `ipAddress` string, nullable — Explicitly requested IP address for the interface. It cannot be specified for Subnet-based interfaces. The least-significant host bit must be 1.
    - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
      - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
    - `isPhysical` boolean — Specifies whether this Subnet or VPC Prefix should be attached to the Instance over physical interface.
    - `device` string — Name of the device to use
    - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
    - `virtualFunctionId` integer, nullable — Index of the virtual function to use, must be specified if isPhysical is false
  - `autoNetwork` boolean — When true, asks NICo to auto-resolve the Instance's network interfaces from the host's underlay (HostInband) network segments. Intended for instances on zero-DPU hosts (or hosts with their DPU in NIC mode). When true: (1) the target VPC's `networkVirtualizationType` MUST be `FLAT`, (2) `interfaces` MUST be empty or omitted, and (3) `secondaryVpcIds` MUST be empty or omitted. Resolved interfaces surface on the Instance's read response.
  - `infinibandInterfaces` InfiniBandInterfaceCreateRequest[] — Associate one or more Partitions with this Instance
    - `partitionId` string, uuid — ID of the Partition the Interface should attach to
    - `device` string — Name of the InfiniBand device to use
    - `vendor` string, nullable — Name of the InfiniBand device vendor, optional
    - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
    - `isPhysical` boolean — Specifies whether this Partition should be attached to the Instance over physical interface
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
  - `dpuExtensionServiceDeployments` DpuExtensionServiceDeploymentRequest[] — DPU Extension Services to deploy to the DPUs of this Instance
    - `dpuExtensionServiceId` string, uuid — ID of the DPU Extension Service to deploy
    - `version` string — Version of the DPU Extension Service to deploy
  - `nvLinkInterfaces` NVLinkInterfaceCreateOrUpdateRequest[] — Define Interfaces to associate Instance GPUs with NVLink Logical Partitions. A subset of GPUs may be specified (it is not required to include all GPUs). Each item references one GPU index (`deviceInstance`) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.
    - `nvLinklogicalPartitionId` string, uuid — ID of the NVLink Logical Partition the Interface should attach to
    - `deviceInstance` integer — GPU index for this NVLink interface. Must be non-negative, unique within the request, and within the GPU count exposed by the selected Machine or Instance Type.
  - `sshKeyGroupIds` string[] — Specify list of SSH Key Group IDs that will provide Serial over LAN access
  - `allowUnhealthyMachine` boolean — Set to true in order to target Machines are in maintenance or have health alerts preventing regular provision flow. Requires Targeted Instance Creation capability enabled for Tenant

## Response `201`

Created

- Instance — Instance is a baremetal Machine that has been provisioned for a Tenant
  - `id` string, uuid — Unique identifier for the Instance
  - `name` string — Name for the Instance
  - `description` string, nullable — Description for the Instance
  - `tenantId` string, uuid — ID of the Tenant the Instance belongs to
  - `infrastructureProviderId` string, uuid — ID of the Infrastructure Provider that owns the Site where the Instance is located
  - `siteId` string, uuid — ID of the Site where the Instance is located
  - `instanceTypeId` string, uuid, nullable
  - `vpcId` string, uuid
  - `secondaryVpcIds` string[] — IDs of VPCs attached to the Instance through non-primary interfaces
  - `machineId` string, nullable
  - `operatingSystemId` string, uuid, nullable
  - `networkSecurityGroupId` string, nullable
  - `networkSecurityGroupPropagationDetails` NetworkSecurityGroupPropagationDetails — The Network Security Group propagation details for a VPC or Instance
    - `id` string, uuid — The VPC or Instance ID
    - `detailedStatus` 'None' | 'Partial' | 'Full' | 'Unknown' | 'Error'
    - `status` 'Synchronizing' | 'Synchronized' | 'Error' — Status values for Network Security Group propagation
    - `details` string, nullable
    - `unpropagatedInstanceIds` string[]
    - `relatedInstanceIds` string[]
  - `networkSecurityGroupInherited` boolean — Indicates if the Network Security Group is inherited from VPC
  - `controllerInstanceId` string, uuid, nullable
  - `ipxeScript` string, nullable
  - `alwaysBootWithCustomIpxe` boolean — Indicates whether the Instance should always execute custom iPXE script when rebooting
  - `phoneHomeEnabled` boolean — Indicates whether the Phone Home service should be enabled or disabled for Instance
  - `userData` string, nullable
  - `labels` Labels
  - `isUpdatePending` boolean — Indicates whether an update is available for the Instance. Updates can be applied on reboot
  - `serialConsoleUrl` string, nullable — Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname
  - `autoNetwork` boolean — True when this Instance uses NICo auto-resolved networking from the host's underlay (HostInband) network segments. When true, the caller's request `interfaces` list was empty, this `interfaces` field remains empty on readback, and the resolved per-interface details surface under `status.network.interfaces`.
  - `interfaces` Interface[]
    - `id` string, uuid
    - `instanceId` string, uuid
    - `subnetId` string, uuid, nullable
    - `vpcPrefixId` string, uuid, nullable
    - `isPhysical` boolean
    - `device` string, nullable — Name of the device to use
    - `deviceInstance` integer, nullable — Index of the device, used to identify which interface card to attache the Partition to
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
    - `macAddress` string, nullable
    - `ipAddresses` string[] — A list of IPv4 or IPv6 addresses
    - `requestedIpAddress` string, nullable — Explicitly requested IP address for the interface. This is only used for VPC Prefix-based interfaces and is not valid for Subnet-based interfaces. The least-significant host bit must be 1.
    - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
      - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for Interface objects
    - `created` string, date-time
    - `updated` string, date-time
  - `infinibandInterfaces` InfiniBandInterface[]
    - `id` string, uuid
    - `instanceId` string, uuid
    - `partitionId` string, uuid — ID of the InfiniBand Partition associated with this interface
    - `device` string — Name of the InfiniBand device associated with this interface
    - `deviceInstance` integer
    - `isPhysical` boolean — Indicates whether this is a physical interface
    - `virtualFunctionId` integer, nullable
    - `guid` string, nullable
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for InfiniBand Interface objects
    - `created` string, date-time
    - `updated` string, date-time
  - `nvLinkInterfaces` NVLinkInterface[]
    - `id` string, uuid
    - `instanceId` string, uuid
    - `nvLinkLogicalPartitionId` string, uuid — ID of the NVLink Logical Partition associated with this interface
    - `nvLinkDomainId` string, uuid, nullable — ID of the NVLink Domain associated with this Interface
    - `deviceInstance` integer — Index of the device, used to identify the GPU associated with this Interface
    - `gpuGuid` string, nullable — Unique ID of the GPU
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for NVLink Interface objects
    - `created` string, date-time
    - `updated` string, date-time
  - `dpuExtensionServiceDeployments` DpuExtensionServiceDeployment[] — DPU Extension Services deployed on DPUs of this Instance
    - `id` string, uuid — Unique identifier for the DPU Extension Service Deployment
    - `dpuExtensionService` DpuExtensionServiceSummary — DPU Extension Service allows user defined services to run on DPUs of their Instances
      - `id` string, uuid — Unique identifier for the DPU Extension Service
      - `name` string — Name for the DPU Extension Service. Must be unique for a given Tenant
      - `serviceType` 'KubernetesPod' — Type of the DPU Extension Service
      - `latestVersion` string, nullable — Latest version of the DPU Extension Service
      - `status` 'Pending' | 'Ready' | 'Error' | 'Deleting' — Status values for DPU Extension Service objects
    - `version` string — Deployed version of the DPU Extension Service
    - `status` 'Pending' | 'Running' | 'Error' | 'Failed' | 'Terminating' — Status values for DPU Extension Service Deployment objects
    - `created` string, date-time — Date/time when this version of the DPU Extension Service Deployment was created
    - `updated` string, date-time — Date/time when this version of the DPU Extension Service Deployment was updated
  - `sshKeyGroupIds` string[] — IDs of SSH Key Groups associated with this Instance
  - `sshKeyGroups` SshKeyGroup[] — IDs of SSH Key Groups associated with this Instance
    - `id` string, uuid — Unique identifier for the SSH Key Group
    - `name` string — Name of the SSH Key Group
    - `description` string, nullable — Description for the SSH Key Group, optional
    - `org` string — Organization this SSH Key Group belongs to
    - `tenantId` string, uuid — ID of the Tenane the SSH Key Group belongs to
    - `version` string, nullable — Version of the SSH Key Group
    - `sshKeys` SshKey[] — SSH Keys associated with this SSH Key Group
      - `id` string, uuid — Unique identifier for the key
      - `name` string
      - `org` string
      - `tenantId` string, uuid
      - `fingerprint` string — SHA256 fingerprint of the public key
      - `created` string, date-time — Date/time when the SSH key was created
      - `updated` string, date-time — Date/time when the SSH key was last updated
    - `siteAssociations` SshKeyGroupSiteAssociation[] — Sites the SSH Key Group is synced to
      - `site` SiteSummary — SiteSummary contains a subset of data for Site object, used when nesting in other objects
        - `id` string, uuid
        - `name` string — Name of the Site
        - `infrastructureProviderId` string, uuid
        - `isSerialConsoleEnabled` boolean — Indicates if Serial Console is enabled for the Site by the Provider
        - `isOnline` boolean — Indicates if the Site is currently reachable from Cloud
        - `capabilities` SiteCapabilities — Boolean flags to indicate features supported by a Site
          - `nativeNetworking` boolean
          - `networkSecurityGroup` boolean
          - `nvLinkPartition` boolean
          - `flow` boolean
          - `imageBasedOperatingSystem` boolean
        - `status` 'Pending' | 'Registered' | 'Error' — Status values for Site objects
      - `status` 'Syncing' | 'Synced' | 'Pending' | 'Error' | 'Deleting' — Status values for SSH Key Group Site Association objects
      - `version` string, nullable — Version of the Key Group on Site
      - `created` string, date-time
      - `updated` string, date-time
    - `status` 'Syncing' | 'Synced' | 'Error' | 'Deleting' — Status values for SSH Key Group objects
    - `statusHistory` StatusDetail[] — History of the SSH Key Group states
      - `status` string
      - `message` string, nullable
      - `created` string, date-time
      - `updated` string, date-time
    - `created` string, date-time — Date/time when the SSH key was created
    - `updated` string, date-time — Date/time when the SSH key was last updated
  - `tpmEkCertificate` string, nullable — base64 encoded TPM EK Certificate associated with this Instance
  - `status` 'Pending' | 'Provisioning' | 'Configuring' | 'Ready' | 'Updating' | 'Repairing' | 'Rebooting' | 'Terminating' | 'Error' — Status values for Instance objects
  - `statusHistory` StatusDetail[]
    - `status` string
    - `message` string, nullable
    - `created` string, date-time
    - `updated` string, date-time
  - `deprecations` Deprecation[]
    - `attribute` string, nullable — Name of the attribute that is deprecated. Omitted if queryParam or endpoint is being deprecated.
    - `queryParam` string, nullable — Query parameter that is deprecated. Omitted if attribute or endpoint is being deprecated.
    - `endpoint` string, nullable — API endpoint that is deprecated. Omitted if attribute or queryParam is being deprecated.
    - `replacedBy` string, nullable — Name of the attribute, query parameter, or endpoint that replaces the deprecated item. Omitted if no replacement is available.
    - `takeActionBy` string, date-time — ISO datetime string for when the deprecated field will no longer be accepted or available in the API
    - `notice` string — Message describing the deprecation
  - `created` string, date-time
  - `updated` string, date-time

## Other responses

- `400` — Error response when request data cannot be validated
- `403` — Error response when user is not authorized to call an endpoint or retrieve/modify objects

## Changes

- **2026-06-02** `15aa8e481b85` — 2 info
  - added the new optional request property `interfaces/items/inlineRoutingProfile`
  - added the optional property `interfaces/items/inlineRoutingProfile` to the response with the `201` status
- **2026-06-02** `b078e63260c1` — 1 warning, 3 info
  - added the new `Repairing` enum value to the `status` response property for the response status `201`
  - added the new optional request property `autoNetwork`
  - the request property `interfaces` became optional
  - added the optional property `autoNetwork` to the response with the `201` status
- **2026-06-02** `568fa8a0d1ed` — 1 info
  - removed the `Repairing` enum value from the `status` response property for the response status `201`
- **2026-06-02** `ffa063523058` — 1 breaking, 2 warning
  - the request property `interfaces` became required
  - removed the request property `autoNetwork`
  - removed the optional property `autoNetwork` from the response with the `201` status
- **2026-06-02** `f20872e0979a` — 3 info
  - added the new optional request property `autoNetwork`
  - the request property `interfaces` became optional
  - added the optional property `autoNetwork` to the response with the `201` status

[Full history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/instance/post.md)

---

[API](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api.md) · [All operations](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nvidia/nvidia-infra-controller-rest-api/revisions/c8ea33c2b23f/schema)