Skip to navigation
API ReferenceOperating System

Retrieve all Operating Systems

View as Markdown

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.

Authentication

AuthorizationBearer
export JWT_BEARER_TOKEN="<jwt-bearer-token>"

# Example org name: "acme-inc
export ORG_NAME=<org-name>

# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

Path parameters

orgstringRequired
Name of the Org

Query parameters

siteIdstringOptional
Filter Operating Systems by Site ID. Can be specified multiple times to filter on more than one ID.
typeenumOptional
Filter Operating Systems by Type
Allowed values:
statusstringOptional
Filter Operating Systems by Status. Can be specified multiple times to filter on more than one status.
querystringOptional
Provide query to search for matches. Input will be matched against name, description and status fields
includeRelationenumOptional
Related entity to expand
Allowed values:
pageNumberintegerOptional1-21474836
Page number for pagination query
pageSizeintegerOptional1-100
Page size for pagination query
orderByenumOptional
Ordering for pagination query

Response headers

X-PaginationstringOptional
Pagination result in JSON format

Response

OK
idstringOptionalRead-onlyformat: "uuid"
ID of the Operating System
namestringOptional2-256 characters
Name of the Operating System
descriptionstring or nullOptional
Optional description of the Operating System
infrastructureProviderIdstring or nullOptionalformat: "uuid"
Specified if a Provider owns the Operating System
tenantIdstring or nullOptionalformat: "uuid"
Specified if a Tenant owns the Operating System
typeenumOptional
Type of the Operating System
Allowed values:
imageUrlstring or nullOptionalformat: "uri"
Original URL from which the Operating System image can be retrieved
imageShastring or nullOptional

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

imageAuthTypeenumOptional
Authentication type for image URL. An empty string means the credentials were cleared through an update.
Allowed values:
imageAuthTokenstring or nullOptional
Auth token to retrieve the image from image URL
imageDiskstring or nullOptionalformat: "^(|smallest|/dev/(nvme[0-9]+n[0-9]+|[sv]d[a-z]+|disk/by-id/[^/\s]+))$"

Whole-disk target that will be overwritten with the image. Accepts smallest, /dev/nvme<controller>n<namespace>, /dev/sd<letters>, /dev/vd<letters>, or /dev/disk/by-id/<identifier>. smallest selects the smallest enumerated whole disk, preferring one with an EFI partition to break a size tie. Partition aliases ending in -part<digits> are rejected. An empty stored value means the Site prefers a disk with an EFI partition, then falls back to the first /dev/nvme<controller>n<namespace>, /dev/sd<letters>, or /dev/vd<letters> whole disk in device-name order.

rootFsIdstring or nullOptional

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

rootFsLabelstring or nullOptional

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

ipxeScriptstring or nullOptional

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

ipxeTemplateIdstring or nullOptional
ID of the iPXE template used, only present for Templated iPXE Operating System
ipxeTemplateParameterslist of objectsOptional

Parameters passed to the iPXE template (Templated iPXE only)

ipxeTemplateArtifactslist of objectsOptional

Artifacts for the iPXE OS definition (Templated iPXE only). authToken is redacted.

userDatastring or nullOptional
User data for the Operating System
isCloudInitbooleanOptional

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

phoneHomeEnabledbooleanOptional
Indicates whether the Phone Home service should be enabled or disabled for Operating System
isActivebooleanOptional
Indicates if the Operating System is active
deactivationNotestring or nullOptional
Optional deactivation note if OS is inactive
allowOverridebooleanOptional
Indicates if the user data can be overridden at Instance creation time
siteAssociationslist of objectsOptional
Sites the Operating System is synced to
statusenumOptional
Status of the Operating System
statusHistorylist of objectsOptional
History of status changes over time
createddatetimeOptionalRead-only

Date/time when the Operating System was created

updateddatetimeOptionalRead-only

Date/time when the Operating System was updated

Errors

403
Forbidden Error