API ReferenceInstance

Retrieve all Instances

View as Markdown

Get all Instances for Tenant.

Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

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

infrastructureProviderIdstringOptionalformat: "uuid"Deprecated

Filter by Infrastructure Provider ID. Deprecated: Instances will no longer be filtered by Infrastructure Provider; results are scoped to the org’s Tenant. Use the siteId parameter to scope results to a specific Infrastructure Provider’s Sites.

siteIdstringOptionalformat: "uuid"
Filter by Site ID. Can be specified multiple times to filter on more than one site.
vpcIdstringOptionalformat: "uuid"
Filter by VPC ID. Can be specified multiple times to filter on more than one VPC.
instanceTypeIdstringOptionalformat: "uuid"
Filter by instance type ID. Can be specified multiple times to filter on more than one instance type.
operatingSystemIdstringOptionalformat: "uuid"
Filter by operating system ID. Can be specified multiple times to filter on more than one operating system.
machineIdstringOptional
Filter by machine ID. Can be specified multiple times to filter on more than one machine.
namestringOptional
Filter by Instance name
statusstringOptional
Filter Instances by Status. Can be specified multiple times to filter on more than one status.
ipAddressstringOptional
Filter by IP address. Can be specified multiple times to filter on more than one IP address.
querystringOptional
Search for matches across all Instances. Input will be matched against name, description, status, and labels fields
includeRelationenumOptional
Related entity to expand
pageNumberintegerOptional>=1Defaults to 1
Page number for pagination query
pageSizeintegerOptional1-100
Page size for pagination query
orderByenumOptional
Ordering for pagination query
networkSecurityGroupIdstringOptional
Filter by Network Security Group ID. Can be specified multiple times to filter on more than one Network Security Group.

Response headers

X-Paginationstring
Pagination result in JSON format

Response

OK
idstringRead-onlyformat: "uuid"
Unique identifier for the Instance
namestring2-256 characters
Name for the Instance
descriptionstring or null
Description for the Instance
tenantIdstringformat: "uuid"
ID of the Tenant the Instance belongs to
infrastructureProviderIdstringformat: "uuid"
ID of the Infrastructure Provider that owns the Site where the Instance is located
siteIdstringformat: "uuid"
ID of the Site where the Instance is located
instanceTypeIdstring or nullformat: "uuid"
ID of the Instance Type
vpcIdstringformat: "uuid"
ID of the VPC
secondaryVpcIdslist of strings

IDs of VPCs attached to the Instance through non-primary interfaces

machineIdstring or null
ID of the Machine
operatingSystemIdstring or nullformat: "uuid"
ID of the Operating System
networkSecurityGroupIdstring or null
ID of the attached Network Security Group, if any
networkSecurityGroupPropagationDetailsobject
Propagation details for the attached Network Security Group
networkSecurityGroupInheritedboolean
Indicates if the Network Security Group is inherited from VPC
controllerInstanceIdstring or nullformat: "uuid"
ID of the Instance in Site Controller
ipxeScriptstring or null
Attribute which is inherited from Operating System
alwaysBootWithCustomIpxeboolean
Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabledboolean
Indicates whether the Phone Home service should be enabled or disabled for the Instance
userDatastring or null
UserData is inherited from Operating System or specified by user if allowed
labelsmap from strings to strings

User-specified Instance labels

isUpdatePendingboolean
Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrlstring or null

Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname

autoNetworkboolean

True when this Instance uses NICo auto-resolved networking from the host’s underlay (HostInband) network segments. When true, the caller’s request interfaces list was empty, this interfaces field remains empty on readback, and the resolved per-interface details surface under status.network.interfaces.

interfaceslist of objects
Interfaces are list of the subnet associated with the Instance
infinibandInterfaceslist of objects
InfiniBandInterfaces are list of the InfiniBandInterface associated with the Instance
nvLinkInterfaceslist of objects
NVLinkInterfaces are list of the NVLinkInterface associated with the Instance
dpuExtensionServiceDeploymentslist of objects
DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIdslist of strings
IDs of SSH Key Groups associated with this Instance
sshKeyGroupslist of objects
IDs of SSH Key Groups associated with this Instance
tpmEkCertificatestring or null
base64 encoded TPM EK Certificate associated with this Instance
statusenum
Status of the Instance
statusHistorylist of objects
Chronological status history for the Instance
deprecationslist of objects
Deprecations active for this resource. Returned only if there are active deprecations.
createddatetimeRead-only

Date/time when the Instance was created

updateddatetimeRead-only

Date/time when the Instance was last updated

Errors

403
Forbidden Error