Sign in

v57

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-08-012143051018.3 KB
Operating System

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

post/v2/org/{org}/nico/operating-system

Request body

namestring required

Name of the Operating System

descriptionstring nullable

Optional description of the Operating System

infrastructureProviderIdstring uuid nullable

Deprecated: Infrastructure Provider is now inferred from org membership.

tenantIdstring uuid nullable

Deprecated: Tenant is now inferred from org membership.

siteIdsstring[]

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.

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

imageUrlstring 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

imageShastring nullable

SHA hash of the image file, required for image-based OS

imageAuthTypestring nullable

Authentication type for image URL, if needed, e.g., basic/bearer/token; required if imageAuthToken is specified

imageAuthTokenstring nullable

Auth token to retrieve the image from image URL, required if imageAuthType is specified

imageDiskstring nullable

Disk path where the image should be mounted, optional

rootFsIdstring nullable

Root filesystem UUID; this or rootFsLabel is required for image-based OS

rootFsLabelstring nullable

Root filesystem label; this or rootFsId is required for image-based OS

phoneHomeEnabledboolean nullable

Indicates whether the Phone Home service should be enabled or disabled for Operating System

userDatastring nullable

User data for the Operating System

isCloudInitboolean

Deprecated and ignored: whether the Operating System is cloud-init based. Value now derived from userData.

allowOverrideboolean

Indicates if the user data can be overridden at Instance creation time

ipxeTemplateIdstring nullable

ID of the iPXE template to use; identifies a Templated iPXE Operating System. Mutually exclusive with ipxeScript and imageUrl.

Example request

{
  "name": "ubuntu-official-22.04",
  "description": "Official Ubuntu 22.04",
  "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  "ipxeScript": "#!ipxe\nkernel http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/linux initrd=initrd.gz\ninitrd http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/initrd.gz\nboot || imgfree\n shell",
  "userData": "#cloud-config\nautoinstall:\n  apt:\n    geoip: true\n    preserve_sources_list: false\n    primary:\n    - arches: [amd64, i386]\n      uri: http://archive.ubuntu.com/ubuntu\n    - arches: [default]\n      uri: http://ports.ubuntu.com/ubuntu-ports",
  "phoneHomeEnabled": true,
  "isCloudInit": true,
  "allowOverride": false
}

Response

Created

idstring uuid

ID of the Operating System

namestring

Name of the Operating System

descriptionstring nullable

Optional description of the Operating System

infrastructureProviderIdstring uuid nullable

Specified if a Provider owns the Operating System

tenantIdstring uuid nullable

Specified if a Tenant owns the Operating System

type'iPXE' | 'Image' | 'TemplatedIpxe' nullable

Type of the Operating System

imageUrlstring uri nullable

Original URL from which the Operating System image can be retrieved

imageShastring nullable

SHA hash of the image file, only present for image-based OS

imageAuthTypestring nullable

Authentication type for image URL, e.g., 'Basic' or 'Bearer'

imageAuthTokenstring nullable

Auth token to retrieve the image from image URL

imageDiskstring nullable

Disk path where the image should be mounted

rootFsIdstring nullable

Root filesystem UUID, only applicable for image-based Operating System

rootFsLabelstring nullable

Root filesystem label, only applicable for image-based Operating System

ipxeScriptstring nullable

iPXE script or URL, only applicable for iPXE-based Operating System

ipxeTemplateIdstring nullable

ID of the iPXE template used, only present for Templated iPXE Operating System

userDatastring nullable

User data for the Operating System

isCloudInitboolean

Whether the Operating System is cloud-init based; true if there is non-empty userData, false otherwise.

phoneHomeEnabledboolean

Indicates whether the Phone Home service should be enabled or disabled for Operating System

isActiveboolean

Indicates if the Operating System is active

deactivationNotestring nullable

Optional deactivation note if OS is inactive

allowOverrideboolean

Indicates if the user data can be overridden at Instance creation time

status'Pending' | 'Provisioning' | 'Syncing' | 'Ready' | 'Deleting' | 'Error' | 'Deactivated'

Status values for Operating System objects

createdstring date-time

Date/time when the Operating System was created

updatedstring date-time

Date/time when the Operating System was updated

Example response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "ubuntu-22.04",
  "description": "Ubuntu 22.04",
  "infrastructureProviderId": null,
  "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  "ipxeScript": "#!ipxe\nkernel http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/linux initrd=initrd.gz\ninitrd http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/initrd.gz\nboot || imgfree\n shell",
  "userData": "#cloud-config\nautoinstall:\n  apt:\n    geoip: true\n    preserve_sources_list: false\n    primary:\n    - arches: [amd64, i386]\n      uri: http://archive.ubuntu.com/ubuntu\n    - arches: [default]\n      uri: http://ports.ubuntu.com/ubuntu-ports\nphone_home:\n  url: http://169.254.169.254:7777/latest/meta-data/phone_home\n  post: all",
  "isCloudInit": true,
  "phoneHomeEnabled": true,
  "isActive": true,
  "deactivationNote": null,
  "allowOverride": false,
  "status": "Pending",
  "statusHistory": [
    {
      "status": "Pending",
      "message": "Request received, pending processing",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}