---
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 — ID of the desired Network Security Group to attach to the Instance
  - `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 — ID of the Subnet to attach to the Interface
    - `vpcPrefixId` string, uuid — ID of the VPC Prefix to attach to the Interface
    - `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 — ID of the Instance Type
  - `vpcId` string, uuid — ID of the VPC
  - `secondaryVpcIds` string[] — IDs of VPCs attached to the Instance through non-primary interfaces
  - `machineId` string, nullable — ID of the Machine
  - `operatingSystemId` string, uuid, nullable — ID of the Operating System
  - `networkSecurityGroupId` string, nullable — ID of the attached Network Security Group, if any
  - `networkSecurityGroupPropagationDetails` NetworkSecurityGroupPropagationDetails — The Network Security Group propagation details for a VPC or Instance
    - `objectId` string, uuid — The ID of the object (VPC/Instance etc.)
    - `detailedStatus` 'None' | 'Partial' | 'Full' | 'Unknown' | 'Error' — The detailed propagation status that was actually returned from NICo
    - `status` 'Synchronizing' | 'Synchronized' | 'Error' — Status values for Network Security Group propagation
    - `details` string, nullable — Additional details for the status
    - `unpropagatedInstanceIds` string[] — IDs of Instances associated with the object that have not yet updated their Network Security Group rules
    - `relatedInstanceIds` string[] — IDs of the instances involved in determining the propagation status
    - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
      - `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 — Date/time by which clients should migrate away from the deprecated API surface
      - `notice` string — Message describing the deprecation
  - `networkSecurityGroupInherited` boolean — Indicates if the Network Security Group is inherited from VPC
  - `controllerInstanceId` string, uuid, nullable — ID of the Instance in Site Controller
  - `ipxeScript` string, nullable — Attribute which is inherited from Operating System
  - `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 the Instance
  - `userData` string, nullable — UserData is inherited from Operating System or specified by user if allowed
  - `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[] — Interfaces are list of the subnet associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the Interface
    - `instanceId` string, uuid — ID of the associated Instance
    - `subnetId` string, uuid, nullable — ID of the associated Subnet
    - `vpcPrefixId` string, uuid, nullable — ID of the associated VPCPrefix
    - `isPhysical` boolean — IsPhysical indicates whether the Subnet is bound on a physical Interface
    - `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 — MAC address of the Interface
    - `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 — Date/time when the Interface was created
    - `updated` string, date-time — Date/time when the Interface was last updated
  - `infinibandInterfaces` InfiniBandInterface[] — InfiniBandInterfaces are list of the InfiniBandInterface associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the InfiniBandInterface
    - `instanceId` string, uuid — ID of the associated Instance
    - `partitionId` string, uuid — ID of the InfiniBand Partition associated with this interface
    - `device` string — Name of the InfiniBand device associated with this interface
    - `vendor` string, nullable — Name of the InfiniBand device vendor associated with this interface
    - `deviceInstance` integer — Index of the device where partition attach to
    - `isPhysical` boolean — Indicates whether this is a physical interface
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
    - `guid` string, nullable — Must be specified if isPhysical is false
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for InfiniBand Interface objects
    - `created` string, date-time — Date/time when the InfiniBandInterface was created
    - `updated` string, date-time — Date/time when the InfiniBandInterface was last updated
  - `nvLinkInterfaces` NVLinkInterface[] — NVLinkInterfaces are list of the NVLinkInterface associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the NVLinkInterface
    - `instanceId` string, uuid — ID of the associated Instance
    - `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 — Date/time when the NVLinkInterface was created
    - `updated` string, date-time — Date/time when the NVLinkInterface was last updated
    - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
      - `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 — Date/time by which clients should migrate away from the deprecated API surface
      - `notice` string — Message describing the deprecation
  - `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 — Name of the SSHKey
      - `org` string — Organization the SSHKey belongs to
      - `tenantId` string, uuid — ID of the Tenant
      - `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 — Unique UUID v4 identifier for the Site
        - `name` string — Name of the Site
        - `infrastructureProviderId` string, uuid — ID of the Infrastructure Provider that owns the Site
        - `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 — Whether the Site supports native networking
          - `networkSecurityGroup` boolean — Whether the Site supports Network Security Groups
          - `nvLinkPartition` boolean — Whether the Site supports NVLink partitioning
          - `flow` boolean — Whether the Site supports Flow-based operations
          - `imageBasedOperatingSystem` boolean — Whether the Site supports image-based operating system provisioning
        - `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 — Date/time when the Site was created
      - `updated` string, date-time — Date/time when the Site was last updated
    - `status` 'Syncing' | 'Synced' | 'Error' | 'Deleting' — Status values for SSH Key Group objects
    - `statusHistory` StatusDetail[] — History of the SSH Key Group states
      - `status` string — State of the associated entity at a particular time
      - `message` string, nullable — Description of the state and cause/remedy in case of error
      - `created` string, date-time — Date/time when the associated entity assumed the status
      - `updated` string, date-time — Date/time when the associated entity was last observed with this status
    - `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[] — Chronological status history for the Instance
    - `status` string — State of the associated entity at a particular time
    - `message` string, nullable — Description of the state and cause/remedy in case of error
    - `created` string, date-time — Date/time when the associated entity assumed the status
    - `updated` string, date-time — Date/time when the associated entity was last observed with this status
  - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
    - `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 — Date/time by which clients should migrate away from the deprecated API surface
    - `notice` string — Message describing the deprecation
  - `created` string, date-time — Date/time when the Instance was created
  - `updated` string, date-time — Date/time when the Instance was last updated

## 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-26** `a8a49b120616` — 1 breaking, 1 info
  - the `interfaces/items/virtualFunctionId` request property's max was decreased to `15.00`
  - the `interfaces/items/virtualFunctionId` request property's min was decreased from `1.00` to `0.00`
- **2026-06-11** `bc7cf73fe604` — 2 warning, 5 info
  - removed the request property `nvLinkInterfaces/items/nvLinklogicalPartitionId`
  - removed the optional property `networkSecurityGroupPropagationDetails/id` from the response with the `201` status
  - added the new optional request property `nvLinkInterfaces/items/nvLinkLogicalPartitionId`
  - added the optional property `infinibandInterfaces/items/vendor` to the response with the `201` status
  - …3 more
- **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`

[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/6c8dcd576e4b/schema)