---
title: "Create Operating System"
method: POST
path: "/v2/org/{org}/nico/operating-system"
tags: ["Operating System"]
---

# Create Operating System

`POST /v2/org/{org}/nico/operating-system`

Create an Operating System for the org.

Ownership is derived from the caller's role:

- Tenant admin (`TENANT_ADMIN`): creates a Tenant-owned Operating System of any type (Image, iPXE, or Templated iPXE).
- Provider admin (`PROVIDER_ADMIN`): may only create Provider-owned Operating Systems of type `Templated iPXE`.

The `tenantId` field in the request body is deprecated; if provided, it must match the org's Tenant.

## Request body

- OperatingSystemCreateRequest — Request data to create an OperatingSystem
  - `name` string, required — Name of the Operating System
  - `description` string, nullable — Optional description of the Operating System
  - `infrastructureProviderId` string, uuid, nullable — Deprecated: Infrastructure Provider is now inferred from org membership.
  - `tenantId` string, uuid, nullable — Deprecated: Tenant is now inferred from org membership.
  - `siteIds` string[] — Target Site for the Operating System. For image-based and Templated iPXE Operating Systems exactly one Site is required, even though this field is an array. The list is fixed at creation and cannot be changed on update. Not applicable to raw iPXE OS.
  - `ipxeScript` string, nullable — Deprecated: raw iPXE Operating Systems are superseded by Templated iPXE (ipxeTemplateId). iPXE script or URL, only applicable for iPXE-based OS. Cannot be specified if imageUrl is specified.
  - `imageUrl` string, uri, nullable — Original URL from which the Operating System image can be retrieved; required for image-based OS. Cannot be specified if ipxeScript is specified
  - `imageSha` string, nullable — SHA hash of the image file, required for image-based OS
  - `imageAuthType` string, nullable — Authentication type for image URL, if needed, e.g., basic/bearer/token; required if imageAuthToken is specified
  - `imageAuthToken` string, nullable — Auth token to retrieve the image from image URL, required if imageAuthType is specified
  - `imageDisk` string, nullable — Disk path where the image should be mounted, optional
  - `rootFsId` string, nullable — Root filesystem UUID; this or `rootFsLabel` is required for image-based OS
  - `rootFsLabel` string, nullable — Root filesystem label; this or `rootFsId` is required for image-based OS
  - `phoneHomeEnabled` boolean, nullable — Indicates whether the Phone Home service should be enabled or disabled for Operating System
  - `userData` string, nullable — User data for the Operating System
  - `isCloudInit` boolean — Deprecated and ignored: whether the Operating System is cloud-init based. Value now derived from `userData`.
  - `allowOverride` boolean — Indicates if the user data can be overridden at Instance creation time
  - `ipxeTemplateId` string, nullable — ID of the iPXE template to use; identifies a Templated iPXE Operating System. Mutually exclusive with ipxeScript and imageUrl.
  - `ipxeTemplateParameters` OperatingSystemIpxeParameter[] — Parameters passed to the iPXE template (Templated iPXE only).
    - `name` string, required — Parameter name (used as a variable in the template)
    - `value` string, required — Parameter value
  - `ipxeTemplateArtifacts` OperatingSystemIpxeArtifact[] — Artifacts (kernel, initrd, ISO, ...) for the iPXE OS definition (Templated iPXE only).
    - `name` string, required — Artifact name
    - `url` string, required — Original URL for the artifact
    - `sha` string, nullable — Optional SHA256 checksum
    - `authType` string, nullable — Optional auth type: Basic or Bearer
    - `authToken` string, nullable — Optional auth token. Redacted in API responses.
    - `cacheStrategy` 'CacheAsNeeded' | 'LocalOnly' | 'CachedOnly' | 'RemoteOnly' — How to handle caching for this artifact

## Response `201`

Created

- OperatingSystem — Describes the attributes of the operating system/bootloader that can be used on instances
  - `id` string, uuid — ID of the Operating System
  - `name` string — Name of the Operating System
  - `description` string, nullable — Optional description of the Operating System
  - `infrastructureProviderId` string, uuid, nullable — Specified if a Provider owns the Operating System
  - `tenantId` string, uuid, nullable — Specified if a Tenant owns the Operating System
  - `type` 'iPXE' | 'Image' | 'TemplatedIpxe', nullable — Type of the Operating System
  - `imageUrl` string, uri, nullable — Original URL from which the Operating System image can be retrieved
  - `imageSha` string, nullable — SHA hash of the image file, only present for image-based OS
  - `imageAuthType` string, nullable — Authentication type for image URL, e.g., 'Basic' or 'Bearer'
  - `imageAuthToken` string, nullable — Auth token to retrieve the image from image URL
  - `imageDisk` string, nullable — Disk path where the image should be mounted
  - `rootFsId` string, nullable — Root filesystem UUID, only applicable for image-based Operating System
  - `rootFsLabel` string, nullable — Root filesystem label, only applicable for image-based Operating System
  - `ipxeScript` string, nullable — iPXE script or URL, only applicable for iPXE-based Operating System
  - `ipxeTemplateId` string, nullable — ID of the iPXE template used, only present for Templated iPXE Operating System
  - `ipxeTemplateParameters` OperatingSystemIpxeParameter[] — Parameters passed to the iPXE template (Templated iPXE only)
    - `name` string, required — Parameter name (used as a variable in the template)
    - `value` string, required — Parameter value
  - `ipxeTemplateArtifacts` OperatingSystemIpxeArtifact[] — Artifacts for the iPXE OS definition (Templated iPXE only). authToken is redacted.
    - `name` string, required — Artifact name
    - `url` string, required — Original URL for the artifact
    - `sha` string, nullable — Optional SHA256 checksum
    - `authType` string, nullable — Optional auth type: Basic or Bearer
    - `authToken` string, nullable — Optional auth token. Redacted in API responses.
    - `cacheStrategy` 'CacheAsNeeded' | 'LocalOnly' | 'CachedOnly' | 'RemoteOnly' — How to handle caching for this artifact
  - `userData` string, nullable — User data for the Operating System
  - `isCloudInit` boolean — Whether the Operating System is cloud-init based; true if there is non-empty `userData`, false otherwise.
  - `phoneHomeEnabled` boolean — Indicates whether the Phone Home service should be enabled or disabled for Operating System
  - `isActive` boolean — Indicates if the Operating System is active
  - `deactivationNote` string, nullable — Optional deactivation note if OS is inactive
  - `allowOverride` boolean — Indicates if the user data can be overridden at Instance creation time
  - `siteAssociations` OperatingSystemSiteAssociation[] — Sites the Operating System 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' | 'Error' | 'Deleting' — Status values for SSH Key Group 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` 'Pending' | 'Provisioning' | 'Syncing' | 'Ready' | 'Deleting' | 'Error' | 'Deactivated' — Status values for Operating System objects
  - `statusHistory` StatusDetail[] — History of status changes over time
    - `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 Operating System was created
  - `updated` string, date-time — Date/time when the Operating System was 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

---

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