---
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.

Either `infrastructureProviderId` or `tenantId` must be provided in request data. Both cannot be provided at the same time.

If `infrastructureProviderId` is provided in request data, then org must have an Infrastructure Provider entity and its ID should match the query parameter value. User must have authorization role with `PROVIDER_ADMIN` suffix.

If `tenantId` is provided in request data, then org must have a Tenant entity and its ID should match the query parameter value. User must have authorization role with `TENANT_ADMIN` suffix.

Only Tenants are allowed to create Operating System for MVP.

## 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 Sites for the Operating System. For image-based OS specify exactly one Site (more than one is not supported). For Templated iPXE OS at least one Site is required and the list is fixed at creation: it 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

## Changes

- **2026-07-29** `c9c451439b06` — 1 warning, 1 info
  - added the new `TemplatedIpxe` enum value to the `type` response property for the response status `201`
  - removed the `Templated iPXE` enum value from the `type` response property for the response status `201`
- **2026-07-23** `af4a60b76e0b` — 1 warning, 7 info
  - added the new `Templated iPXE` enum value to the `type` response property for the response status `201`
  - added the new optional request property `ipxeTemplateArtifacts`
  - added the new optional request property `ipxeTemplateId`
  - added the new optional request property `ipxeTemplateParameters`
  - …4 more
- **2026-07-02** `3f2849e9c157` — 1 info
  - request property `isCloudInit` deprecated

[Change history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/operating-system/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.dev/nvidia/apis/nvidia-infra-controller-rest-api/revisions/3e4af06d1289?raw)