Sign in
Operating System

Retrieve all Operating Systems

List Operating Systems visible to the caller.

User must have an authorization role with either the PROVIDER_ADMIN or TENANT_ADMIN suffix for the org.

  • Provider admin: returns only Operating Systems owned by the org's Infrastructure Provider.
  • Tenant admin: returns Operating Systems owned by the caller's Tenant, plus Provider-owned Operating Systems that are associated with at least one Site the Tenant can access.
  • Dual-role (both Provider and Tenant): returns the union of the Tenant's and the Provider's Operating Systems.
get/v2/org/{org}/nico/operating-system

Query parameters

siteIdstring

Filter Operating Systems by Site ID. Can be specified multiple times to filter on more than one ID.

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

Filter Operating Systems by Type

statusstring

Filter Operating Systems by Status. Can be specified multiple times to filter on more than one status.

querystring

Provide query to search for matches. Input will be matched against name, description and status fields

includeRelation'InfrastructureProvider' | 'Tenant'

Related entity to expand

pageNumberinteger

One-indexed page number.

Page number for pagination query

pageSizeinteger
Example:20

Page size for pagination query

orderBy'NAME_ASC' | 'NAME_DESC' | 'STATUS_ASC' | 'STATUS_DESC' | 'CREATED_ASC' | 'CREATED_DESC' | 'UPDATED_ASC' | 'UPDATED_DESC'

Ordering for pagination query

Response

OK

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/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"
  }
]

Changes

Changed in 5 of the 90 revisions of this API.138

  • 9c78a8936b341See the full diff
    • ○

      added the optional property items/siteAssociations/items/site/capabilities/dpsPowerManagement to the response with the 200 status

      response-optional-property-added

  • a482c2d8f5e21See the full diff
    • ○

      added the optional property items/siteAssociations/items/site/capabilities/vpcSlaac to the response with the 200 status

      response-optional-property-added

  • c459c6587dee1See the full diff
    • ●

      for the query request parameter pageNumber, the max was set to 21474836.00

      request-parameter-max-set

  • c9c451439b06112See the full diff
    • ▲

      removed the enum value Templated iPXE from the query request parameter type

      request-parameter-enum-value-removed

    • ●

      added the new TemplatedIpxe enum value to the items/type response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new enum value TemplatedIpxe to the query request parameter type

      request-parameter-enum-value-added

    • ○

      removed the Templated iPXE enum value from the items/type response property for the response status 200

      response-property-enum-value-removed

  • af4a60b76e0b14See the full diff
    • ●

      added the new Templated iPXE enum value to the items/type response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new enum value Templated iPXE to the query request parameter type

      request-parameter-enum-value-added

    • ○

      added the optional property items/ipxeTemplateArtifacts to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property items/ipxeTemplateId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property items/ipxeTemplateParameters to the response with the 200 status

      response-optional-property-added