NCX Infra Controller REST API (1.4.0)

Download OpenAPI specification:

NCX Infra Controller REST API is the centralized RESTful gateway to access NCX Infra Controller service

NCX Infra Controller REST API allows users to create and manage resources e.g. VPC, Subnets, Instances across all connected NCX Infra Controller datacenters, also referred to as Sites.

Getting Started

This section provides a quick overview of the API and how to get started.

Authentication

The first step is to authenticate using a JWT bearer token. Organization structures and roles depend on the authentication configuration used. For details on authentication, please consult the NICo REST auth module README.

API Version

The next step is to be aware of the API version being used. The API version can be retrieved by calling the Retrieve Metadata endpoint. In general, the API maintains backward compatibility with the previous versions. Any breaking changes are announced using a deprecation notice. Current and past deprecations are listed in the Deprecations section.

Service Account Mode

Depending on the auth configuration used, the NICo REST API may be configured in Service Account mode. In this mode, API users can act as both Provider and Tenant as part of the same organization. If this is the case, the user must first retrieve the Service Account by making a call to the Retrieve Service Account endpoint. For service accounts, the Tenant entity is initialized as a privileged Tenant with targetedInstanceCreation capability enabled.

Provider or Tenant Mode

If NICo REST API is not configured in Service Account mode, the user should retrieve the Infrastructure Provider by making a call to the Retrieve Infrastructure Provider endpoint or the Tenant by making a call to the Retrieve Tenant endpoint.

In both cases, these calls initialize Provider and Tenant entities for the organization. All resources created are anchored to either the Provider or Tenant entity.

Once the Provider and the Tenant are initialized, the user can create resources by making calls to the appropriate endpoints.

Creating Site Level IP Blocks

To utilize a NICo Site, the Provider or Service Account holder must create IP Blocks for each network overlay defined in NICo Core Site configuration toml file.

To create an IP Block, the user must make a call to the Create IP Block endpoint.

Note: From this point onwards, a brief outline is provided for the typical API call flows for various use cases.

Typical API Call Flow for Service Account

Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in. For Disconnected NICo installations where NICo REST is deployed alongside NICo Core, typically there will be a single Site available.
For each Site IP Block, create a Network Allocation for the Tenant entity using the Create Allocation endpoint using the full prefix length. This will create a Tenant IP Block for each Site IP Block.
- Creating an Allocation will create the Tenant in NICo Core.
Create a VPC using the Create VPC endpoint.
Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block
- If the Site supports Native Networking (FNN), create a VPC Prefix using the Create VPC Prefix endpoint. Otherwise the user should create a Subnet using the Create Subnet endpoint.
Create an Operating System using the Create Operating System endpoint specifying iPXE script and user data.
Retrieve available Machines on Site using the Retrieve All Machines endpoint
Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Machine

Typical API Call Flow for Provider

Create a Tenant Account using the Create Tenant Account endpoint. Provider must know the Tenant org name.
Once the Tenant has accepted the Tenant Account, the Provider can allocate resources to the Tenant.
Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in.
Create an Instance Type using the Create Instance Type endpoint
Retrieve available Machines on Site using the Retrieve All Machines endpoint
Update a Machine's Instance Type using the Update Machine endpoint or assign multiple Machines to an Instance Type using the Create Instance Type/Machine Association endpoint
Create a Compute Allocation for Tenant using the Create Compute Allocation endpoint referencing the Instance Type
- Creating any type of Allocation for a Tenant will create the Tenant in NICo Core.
Create a Network Allocation for Tenant using the Create Allocation endpoint referencing a Site IP Block
- Creating a Network Allocation will create a Tenant IP Block

Typical API Call Flow for Tenant

Accept the Tenant Account using the Update Tenant Account endpoint.
Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in. Any Site where the Tenant has an Allocation will be returned.
Create a VPC using the Create VPC endpoint.
Retrieve available Site IP Blocks using the Retrieve All IP Blocks endpoint. Any IP Block for which the Tenant has received a Network Allocation from the Provider will be returned.
Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block
- Site supports Native Networking (FNN), create a VPC Prefix using the Create VPC Prefix endpoint
- Otherwise the user should create a Subnet using the Create Subnet endpoint
Create an Operating System using the Create Operating System endpoint specifying iPXE script and user data.
Retrieve available Instance Types using the Retrieve All Instance Types endpoint. Any Instance Type for which the Tenant has received a Compute Allocation from the Provider will be returned.
Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Instance Type

Service Account

When API service is configured in Service Account mode, API users can act as both Provider and Tenant. For service accounts, the Tenant entity is initialized as a privileged Tenant with targetedInstanceCreation capability enabled.

Retrieve Service Account status for current org

API service must be configured for Service Account access at the time of deployment. It cannot be enabled or disabled via API.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

enabled	boolean Indicates whether Service Account is enabled
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider associated with Service Account
tenantId	string <uuid> ID of the Tenant associated with Service Account

Response samples

200
403

Content type

application/json

{"enabled": true,
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
}

Infrastructure Provider

Infrastructure Provider is the anchor entity for an organization that owns and manages Site resources.

Deprecation history:

name attribute was deprecated and was removed on August 17th, 2023 0:00 UTC. Please use orgDisplayName instead.
POST /org/:orgName/carbide/infrastructure-provider endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Providers are automatically created when retrieved by a Provider Admin.
PATCH /org/:orgName/carbide/infrastructure-provider/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Provider details are populated from Org information and cannot be updated by the user.

Retrieve Infrastructure Provider for current Org

Retrieve Infrastructure Provider entity for current Org.

User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

id	string <uuid>
org	string
orgDisplayName	string
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"org": "rf43bbtnb9c5",
"orgDisplayName": "Dell Corporation",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve Stats for current Infrastructure Provider

Retrieve stats for current Infrastructure Provider.

User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

	object (MachineCountByStatus) Describes count of Machines in various statuses
	object (IpBlockCountByStatus) Describes counts of IP Blocks in various statuses
	object (TenantAccountCountByStatus) Describes counts of Tenant Accounts in various statuses

Response samples

200
403

Content type

application/json

{"machine": {"total": 27,
"initializing": 8,
"assigned": 12,
"ready": 5,
"error": 2,
"decommissioned": 0,
"unknown": 0
},
"ipBlock": {"total": 4,
"pending": 1,
"provisioning": 1,
"ready": 2,
"deleting": 0,
"error": 0
},
"tenantAccount": {"total": 8,
"pending": 0,
"invited": 3,
"ready": 5,
"error": 0
}
}

Tenant

Tenant is the anchor entity for an organization that consumes Network and Compute resources on a Site.

Deprecation history:

name attribute was deprecated and was removed on August 17th, 2023. Please use orgDisplayName instead.
enableSSHAccess attribute was deprecated and was removed on August 17th, 2023 0:00 UTC. Please use 'isSerialConsoleSSHKeysEnabled' attribute of Site instead.
POST /org/:orgName/carbide/tenant endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenants are automatically created when retrieved by a Tenant Admin.
PATCH /org/:orgName/carbide/tenant/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenant details are populated from Org information and cannot be updated by the user.

Retrieve Tenant for current Org

Retrieve Tenant entity for current Org.

User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

id	string <uuid> Unique ID of the Tenant
org	string Name/external ID of Tenant's organization
orgDisplayName	string Display name of Tenant's organization
created	string <date-time> Date/time the Tenant was created
updated	string <date-time> Date/time when Tenant was last updated
	object (TenantCapabilities) Features that are enabled/disabled for Tenant

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"org": "qygdmg8oqik8",
"orgDisplayName": "Echo Corporation",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z",
"capabilities": {"targetedInstanceCreation": false
}
}

Retrieve Stats for current Tenant

Retrieve stats for current Tenant.

User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

	object (InstanceCountByStatus) Describes count of Instances in various statuses
	object (VpcCountByStatus) Describes counts of VPCs in various statuses
	object (SubnetCountByStatus) Describes counts of Subnets in various statuses

Response samples

200
403

Content type

application/json

{"instance": {"total": 12,
"pending": 2,
"provisioning": 1,
"ready": 8,
"terminating": 2,
"error": 1
},
"vpc": {"total": 4,
"pending": 1,
"provisioning": 1,
"ready": 2,
"deleting": 0,
"error": 0
},
"subnet": {"total": 4,
"pending": 1,
"provisioning": 1,
"ready": 2,
"deleting": 0,
"error": 0
}
}

Retrieve per-tenant instance type allocation stats for a site

Returns instance type allocation stats grouped by tenant for the specified site.

User must have FORGE_PROVIDER_ADMIN authorization role. The specified site must belong to the Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Tenant
org	string Organization name for the Tenant
orgDisplayName	string Display name for the Tenant's organization
	Array of objects (InstanceTypeStats)

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"org": "string",
"orgDisplayName": "string",
"instanceTypes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"allocated": 0,
"usedMachineStats": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
},
"maxAllocatable": 0,
"allocations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"total": 0
}
]
}
]
}
]

Tenant Account

Tenant Account connects a Tenant with an Infrastructure Provider. It represents/contains any information pertaining to their relationship.

Retrieve all Tenant Accounts

Retrieve all Tenant Accounts.

Either infrastructureProviderId or tenantId query param must be specified.

If infrastructureProviderId query param is provided, then org must have an Infrastructure Provider entity and its ID should match the query param value. User must have FORGE_PROVIDER_ADMIN role.

If tenantId query param is provided, then org must have a Tenant entity and its ID should match the query param value. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

infrastructureProviderId	string <uuid> Filter TenantAccounts by Infrastructure Provider ID
tenantId	string <uuid> Filter TenantAccounts by Tenant ID
query	string Search string to filter Tenant Accounts by account number, tenant org, or tenant org display name
includeRelation	string Enum: "InfrastructureProvider" "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ACCOUNT_NUMBER_ASC" "ACCOUNT_NUMBER_DESC" "TENANT_ORG_NAME_ASC" "TENANT_ORG_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "TENANT_CONTACT_EMAIL_ASC" "TENANT_CONTACT_EMAIL_DESC" "TENANT_CONTACT_FULL_NAME_ASC" "TENANT_CONTACT_FULL_NAME_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
infrastructureProviderId	string <uuid>
infrastructureProviderOrg	string
tenantId	string or null <uuid>
tenantOrg	string or null
	object (User) Details of the user collected from authentication tokens
allocationCount	integer
status	string (TenantAccountStatus) Enum: "Pending" "Invited" "Ready" "Error" Status values for Tenant Account objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"infrastructureProviderOrg": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"tenantOrg": "rf43bbtnb9c5",
"tenantContact": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "janed@nvidia.com",
"firstName": "Jane",
"lastName": "Doe",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
"allocationCount": 0,
"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"
}
]

Create Tenant Account

Create a Tenant Account.

Org must have an Infrastructure Provider entity and its ID must match the Infrastructure Provider ID in request data. User must have FORGE_PROVIDER_ADMIN authorization role

Infrastructure Provider can create a Tenant Account by specifying the Tenant's UUID or Tenant's org name. This will set the status of the Tenant Account to "Invited". Then the Tenant can view this account information and are able to confirm/accept the account by updating the Tenant Account.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

infrastructureProviderId required	string <uuid>
tenantOrg required	string non-empty ^[A-Za-z0-9-_]+$ Must be a valid Org name

Responses

Response Schema: application/json

id	string <uuid>
infrastructureProviderId	string <uuid>
infrastructureProviderOrg	string
tenantId	string or null <uuid>
tenantOrg	string or null
	object (User) Details of the user collected from authentication tokens
allocationCount	integer
status	string (TenantAccountStatus) Enum: "Pending" "Invited" "Ready" "Error" Status values for Tenant Account objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantOrg": "rf43bbtnb9c5"
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"infrastructureProviderOrg": "xskkpgqpeakn",
"tenantId": null,
"tenantOrg": "rf43bbtnb9c5",
"tenantContact": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "janed@nvidia.com",
"firstName": "Jane",
"lastName": "Doe",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
"allocationCount": 0,
"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"
}

Retrieve Tenant Account

Retrieve a Tenant Account by ID

Either infrastructureProviderId or tenantId query param must be specified.

If infrastructureProviderId query param is provided, then org must have an Infrastructure Provider entity and its ID should match the query param value. User must have FORGE_PROVIDER_ADMIN role.

If tenantId query param is provided, then org must have a Tenant entity and its ID should match the query param value. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
accountId required	string <uuid> ID of the Tenant Account

query Parameters

infrastructureProviderId	string <uuid> Filter Tenant Accounts by Infrastructure Provider ID
tenantId	string <uuid> Filter Tenant Accounts by Tenant ID
includeRelation	string Enum: "InfrastructureProvider" "Tenant" Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
infrastructureProviderId	string <uuid>
infrastructureProviderOrg	string
tenantId	string or null <uuid>
tenantOrg	string or null
	object (User) Details of the user collected from authentication tokens
allocationCount	integer
status	string (TenantAccountStatus) Enum: "Pending" "Invited" "Ready" "Error" Status values for Tenant Account objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"infrastructureProviderOrg": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"tenantOrg": "rf43bbtnb9c5",
"tenantContact": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "janed@nvidia.com",
"firstName": "Jane",
"lastName": "Doe",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
"allocationCount": 2,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Account ready, Tenant accepted invite",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"status": "Invited",
"message": "Request received, pending Tenant acceptance",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Update Tenant Account

Update a Tenant Account.

Can be used to accept an invitation sent by Infrastructure Provider.

Org must have a tenant entity whose ID matches the tenantId of the Tenant Account object. User must have FORGE_TENANT_ADMIN role. Can only update a TenantAccount that has Invited status.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
accountId required	string <uuid> ID of the Tenant Account

Request Body schema: application/json

No params needed, an empty request body will suffice.

object (TenantAccountUpdateRequest)

Request data to update a TenantAccount.

No params needed, an empty request will suffice.

Responses

Response Schema: application/json

id	string <uuid>
infrastructureProviderId	string <uuid>
infrastructureProviderOrg	string
tenantId	string or null <uuid>
tenantOrg	string or null
	object (User) Details of the user collected from authentication tokens
allocationCount	integer
status	string (TenantAccountStatus) Enum: "Pending" "Invited" "Ready" "Error" Status values for Tenant Account objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"infrastructureProviderOrg": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"tenantOrg": "rf43bbtnb9c5",
"tenantContact": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "janed@nvidia.com",
"firstName": "Jane",
"lastName": "Doe",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
"allocationCount": 0,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Account ready, Tenant accepted invite",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"status": "Invited",
"message": "Request received, pending Tenant acceptance",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Tenant Account

Delete a Tenant Account by ID.

Org must have an Infrastructure Provider entity, specified Tenant Account must be created by said Provider. Requesting user must have FORGE_PROVIDER_ADMIN role.

Tenant cannot delete a Tenant Account.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
accountId required	string <uuid> ID of the Tenant Account

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Site

Site is a datacenter that contains physical hardware and networking resources. All resources created by Provider or Tenant are directly or indirectly anchored to the Site object.

Retrieve all Sites

Retrieve all Sites for org.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role. infrastructureProviderId or tenantId query param may be required for older API versions.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

infrastructureProviderId	string <uuid> Filter Sites by Infrastructure Provider ID
tenantId	string <uuid> Filter Sites by Tenant ID
status	string Filter Sites by Status. Can be specified multiple times to filter on more than one status
isNativeNetworkingEnabled	boolean Filter Sites by native networking enabled flag. Requires Provider Admin role.
isNetworkSecurityGroupEnabled	boolean Filter Sites by network security group enabled flag. Requires Provider Admin role.
isNVLinkPartitionEnabled	boolean Filter Sites by NVLink partitioning enabled flag. Requires Provider Admin role.
isRackLevelAdministrationEnabled	boolean Filter Sites by Rack Level Administration enabled flag. Requires Provider Admin role.
includeMachineStats	boolean Include a breakdown of Machine counts by life-cycle status and health. Requires Provider Admin role.
query	string Search for matches across all Sites. Input will be matched against name, description, location, contact, and status fields
includeRelation	string Value: "InfrastructureProvider" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "DESCRIPTION_ASC" "DESCRIPTION_DESC" "LOCATION_ASC" "LOCATION_DESC" "CONTACT_ASC" "CONTACT_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the Site
description	string Optional description for the Site
org	string
infrastructureProviderId	string <uuid>
siteControllerVersion	string Version of the Site Controller software
siteAgentVersion	string Version of the Site Agent software
registrationToken	string Token that can be used to register a Site. Value only exposed to Provider
registrationTokenExpiration	string <date-time> Date/time when registration token expires. Value only exposed to Provider
serialConsoleHostname	string <hostname>
isSerialConsoleEnabled	boolean Indicates if Serial Console is enabled for the Site by the Provider
serialConsoleIdleTimeout	integer or null Maximum idle time in seconds before Serial Console is disconnected
serialConsoleMaxSessionLength	integer or null Maximum length of Serial Console session in seconds
isSerialConsoleSSHKeysEnabled	boolean Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant
isOnline	boolean Indicates if the Site is currently reachable from Cloud
status	string (SiteStatus) Enum: "Pending" "Registered" "Error" Status values for Site objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site
	object (SiteCapabilities) Boolean flags to indicate features supported by a Site
	object (SiteMachineStats) Machine stats for a Site

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "San Jose Central 4",
"description": "Datacenter serving the San Jose central region",
"org": "qygdmg8oqik8",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteControllerVersion": "0.1",
"siteAgentVersion": "0.1",
"registrationToken": "J7KO-89RR-Y7WQ-AD90",
"registrationTokenExpiration": "2019-08-25T12:00:00Z",
"serialConsoleHostname": "sjc.carbide.acme.com",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 60,
"serialConsoleMaxSessionLength": 3600,
"isSerialConsoleSSHKeysEnabled": true,
"machineStats": {"total": 15,
"totalByStatus": {"Initializing": 0,
"Ready": 7,
"Reset": 0,
"Maintenance": 0,
"InUse": 3,
"Error": 5,
"Decommissioned": 0,
"Unknown": 0
},
"totalByHealth": {"healthy": 12,
"unhealthy": 3
},
"totalByStatusAndHealth": {"Initializing": {"healthy": 0,
"unhealthy": 0
},
"Ready": {"healthy": 5,
"unhealthy": 0
},
"Reset": {"healthy": 0,
"unhealthy": 0
},
"Maintenance": {"healthy": 5,
"unhealthy": 0
},
"InUse": {"healthy": 3,
"unhealthy": 0
},
"Error": {"healthy": 2,
"unhealthy": 3
},
"Decommissioned": {"healthy": 0,
"unhealthy": 0
},
"Unknown": {"healthy": 0,
"unhealthy": 0
}
},
"totalByAllocation": {"allocatedInUse": 3,
"allocatedNotInUse": 3,
"unallocated": 5
}
},
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"isOnline": 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",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}
]

Create Site

Create a Site for the org.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Tenants cannot create Sites.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Name for the Site
description	string Description for the Site
serialConsoleHostname	string <hostname> Hostname to reach Serial Console for the Site
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the Site
description	string Optional description for the Site
org	string
infrastructureProviderId	string <uuid>
siteControllerVersion	string Version of the Site Controller software
siteAgentVersion	string Version of the Site Agent software
registrationToken	string Token that can be used to register a Site. Value only exposed to Provider
registrationTokenExpiration	string <date-time> Date/time when registration token expires. Value only exposed to Provider
serialConsoleHostname	string <hostname>
isSerialConsoleEnabled	boolean Indicates if Serial Console is enabled for the Site by the Provider
serialConsoleIdleTimeout	integer or null Maximum idle time in seconds before Serial Console is disconnected
serialConsoleMaxSessionLength	integer or null Maximum length of Serial Console session in seconds
isSerialConsoleSSHKeysEnabled	boolean Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant
isOnline	boolean Indicates if the Site is currently reachable from Cloud
status	string (SiteStatus) Enum: "Pending" "Registered" "Error" Status values for Site objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site
	object (SiteCapabilities) Boolean flags to indicate features supported by a Site
	object (SiteMachineStats) Machine stats for a Site

Request samples

Payload

Content type

application/json

{"name": "San Jose Central 4",
"description": "Datacenter serving San Jose central region",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "San Jose Central 4",
"description": "Datacenter serving the San Jose central region",
"org": "qygdmg8oqik8",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteControllerVersion": "0.1",
"siteAgentVersion": "0.1",
"registrationToken": "J7KO-89RR-Y7WQ-AD90",
"registrationTokenExpiration": "2019-08-25T12:00:00Z",
"serialConsoleHostname": "sjc.carbide.acme.com",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 60,
"serialConsoleMaxSessionLength": 3600,
"isSerialConsoleSSHKeysEnabled": true,
"machineStats": {"total": 15,
"totalByStatus": {"Initializing": 0,
"Ready": 7,
"Reset": 0,
"Maintenance": 0,
"InUse": 3,
"Error": 5,
"Decommissioned": 0,
"Unknown": 0
},
"totalByHealth": {"healthy": 12,
"unhealthy": 3
},
"totalByStatusAndHealth": {"Initializing": {"healthy": 0,
"unhealthy": 0
},
"Ready": {"healthy": 5,
"unhealthy": 0
},
"Reset": {"healthy": 0,
"unhealthy": 0
},
"Maintenance": {"healthy": 5,
"unhealthy": 0
},
"InUse": {"healthy": 3,
"unhealthy": 0
},
"Error": {"healthy": 2,
"unhealthy": 3
},
"Decommissioned": {"healthy": 0,
"unhealthy": 0
},
"Unknown": {"healthy": 0,
"unhealthy": 0
}
},
"totalByAllocation": {"allocatedInUse": 3,
"allocatedNotInUse": 3,
"unallocated": 5
}
},
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"isOnline": 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",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}

Retrieve Site

Retrieve a specific Site by ID.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Access is granted if:

The Site is owned by the org's Infrastructure Provider
The org's Tenant has an Allocation for Site
The org's Tenant is privileged and has Account with Site's Provider

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
siteId required	string <uuid> ID of the Site

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the Site
description	string Optional description for the Site
org	string
infrastructureProviderId	string <uuid>
siteControllerVersion	string Version of the Site Controller software
siteAgentVersion	string Version of the Site Agent software
registrationToken	string Token that can be used to register a Site. Value only exposed to Provider
registrationTokenExpiration	string <date-time> Date/time when registration token expires. Value only exposed to Provider
serialConsoleHostname	string <hostname>
isSerialConsoleEnabled	boolean Indicates if Serial Console is enabled for the Site by the Provider
serialConsoleIdleTimeout	integer or null Maximum idle time in seconds before Serial Console is disconnected
serialConsoleMaxSessionLength	integer or null Maximum length of Serial Console session in seconds
isSerialConsoleSSHKeysEnabled	boolean Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant
isOnline	boolean Indicates if the Site is currently reachable from Cloud
status	string (SiteStatus) Enum: "Pending" "Registered" "Error" Status values for Site objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site
	object (SiteCapabilities) Boolean flags to indicate features supported by a Site
	object (SiteMachineStats) Machine stats for a Site

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "San Jose Central 4",
"description": "Datacenter serving the San Jose central region",
"org": "qygdmg8oqik8",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteControllerVersion": "0.1",
"siteAgentVersion": "0.1",
"registrationToken": "J7KO-89RR-Y7WQ-AD90",
"registrationTokenExpiration": "2019-08-25T12:00:00Z",
"serialConsoleHostname": "sjc.carbide.acme.com",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 60,
"serialConsoleMaxSessionLength": 3600,
"isSerialConsoleSSHKeysEnabled": true,
"machineStats": {"total": 15,
"totalByStatus": {"Initializing": 0,
"Ready": 7,
"Reset": 0,
"Maintenance": 0,
"InUse": 3,
"Error": 5,
"Decommissioned": 0,
"Unknown": 0
},
"totalByHealth": {"healthy": 12,
"unhealthy": 3
},
"totalByStatusAndHealth": {"Initializing": {"healthy": 0,
"unhealthy": 0
},
"Ready": {"healthy": 5,
"unhealthy": 0
},
"Reset": {"healthy": 0,
"unhealthy": 0
},
"Maintenance": {"healthy": 5,
"unhealthy": 0
},
"InUse": {"healthy": 3,
"unhealthy": 0
},
"Error": {"healthy": 2,
"unhealthy": 3
},
"Decommissioned": {"healthy": 0,
"unhealthy": 0
},
"Unknown": {"healthy": 0,
"unhealthy": 0
}
},
"totalByAllocation": {"allocatedInUse": 3,
"allocatedNotInUse": 3,
"unallocated": 5
}
},
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"isOnline": 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",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}

Update Site

Update a specific Site

User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider updating the Site must be the owner of the Site. At present, there are no Site specific configuration modifiable by Tenant.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
siteId required	string <uuid> ID of the Site

Request Body schema: application/json

name	string Update name of the Site. Can only be updated by Provider
description	string Update description for the Site. Can only be updated by Provider
renewRegistrationToken	boolean Set to true to issue a new registration token. Can only be updated by Provider
serialConsoleHostname	string <hostname> Hostname to reach Serial Console for the Site. Can only be updated by Provider
isSerialConsoleEnabled	boolean Deprecated Enable/disable Serial Console. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.
serialConsoleIdleTimeout	integer Deprecated Maximum idle time in seconds before Serial Console is disconnected. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.
serialConsoleMaxSessionLength	integer Deprecated Maximum length of Serial Console session in seconds. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.
isSerialConsoleSSHKeysEnabled	boolean Deprecated Enable/disable Serial Console access using SSH Keys. Previously updateable only by Tenants, modifying this value is no longer supported, update SSH Key Groups to remove Site instead.
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the Site
description	string Optional description for the Site
org	string
infrastructureProviderId	string <uuid>
siteControllerVersion	string Version of the Site Controller software
siteAgentVersion	string Version of the Site Agent software
registrationToken	string Token that can be used to register a Site. Value only exposed to Provider
registrationTokenExpiration	string <date-time> Date/time when registration token expires. Value only exposed to Provider
serialConsoleHostname	string <hostname>
isSerialConsoleEnabled	boolean Indicates if Serial Console is enabled for the Site by the Provider
serialConsoleIdleTimeout	integer or null Maximum idle time in seconds before Serial Console is disconnected
serialConsoleMaxSessionLength	integer or null Maximum length of Serial Console session in seconds
isSerialConsoleSSHKeysEnabled	boolean Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant
isOnline	boolean Indicates if the Site is currently reachable from Cloud
status	string (SiteStatus) Enum: "Pending" "Registered" "Error" Status values for Site objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	object (SiteLocation) Location of the Site
	object (SiteContact) Contact for the Site
	object (SiteCapabilities) Boolean flags to indicate features supported by a Site
	object (SiteMachineStats) Machine stats for a Site

Request samples

Payload

Content type

application/json

Example

example-1

{"name": "San Jose Central No.4",
"description": "Datacenter 4 serving central San Jose",
"renewRegistrationToken": true,
"serialConsoleHostname": "sol.carbide.acme.com",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "San Jose Central 4",
"description": "Datacenter serving the San Jose central region",
"org": "qygdmg8oqik8",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteControllerVersion": "0.1",
"siteAgentVersion": "0.1",
"registrationToken": "J7KO-89RR-Y7WQ-AD90",
"registrationTokenExpiration": "2019-08-25T12:00:00Z",
"serialConsoleHostname": "sjc.carbide.acme.com",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 60,
"serialConsoleMaxSessionLength": 3600,
"isSerialConsoleSSHKeysEnabled": true,
"machineStats": {"total": 15,
"totalByStatus": {"Initializing": 0,
"Ready": 7,
"Reset": 0,
"Maintenance": 0,
"InUse": 3,
"Error": 5,
"Decommissioned": 0,
"Unknown": 0
},
"totalByHealth": {"healthy": 12,
"unhealthy": 3
},
"totalByStatusAndHealth": {"Initializing": {"healthy": 0,
"unhealthy": 0
},
"Ready": {"healthy": 5,
"unhealthy": 0
},
"Reset": {"healthy": 0,
"unhealthy": 0
},
"Maintenance": {"healthy": 5,
"unhealthy": 0
},
"InUse": {"healthy": 3,
"unhealthy": 0
},
"Error": {"healthy": 2,
"unhealthy": 3
},
"Decommissioned": {"healthy": 0,
"unhealthy": 0
},
"Unknown": {"healthy": 0,
"unhealthy": 0
}
},
"totalByAllocation": {"allocatedInUse": 3,
"allocatedNotInUse": 3,
"unallocated": 5
}
},
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"isOnline": 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",
"location": {"city": "San Jose",
"state": "CA",
"country": "USA"
},
"contact": {"email": "johndoe@nvidia.com"
}
}

Delete Site

Delete a specific Site

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Site can only be deleted if all Allocations have been deleted.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
siteId required	string <uuid> ID of the Site

query Parameters

purgeMachines

boolean

Scrub all Machine data associated with this Site to re-pair

Responses

Retrieve Site status history

Retrieve a specific Site status history

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Access is granted if:

The Site is owned by the org's Infrastructure Provider
The org's Tenant has an Allocation for Site
The org's Tenant is privileged and has Account with Site's Provider

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
siteId required	string <uuid> ID of the Site

query Parameters

pageNumber	integer Page number for pagination query
pageSize	integer Page size for pagination query
orderBy	string Ordering for pagination query

Responses

Response Headers
X-Pagination	string Pagination result in JSON format

Response Schema: application/json

Array

status	string
message	string
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Allocation

Allocations are the mechanism by which Provider can delegate Network and Compute resources to Tenant.

Retrieve all Allocations

Retrieve all Allocations for the org.

Provider and Tenant roles are inferred from the org's membership. User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Results are returned from both Provider and Tenant perspectives when the org has both roles.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

infrastructureProviderId	string <uuid> Deprecated Filter Allocations by Infrastructure Provider ID.
tenantId	string <uuid> Filter Allocations by Tenant ID.
siteId	string <uuid> Filter Allocations by Site ID. Can be specified multiple times to filter on more than one Site ID.
id	string Filter Allocations by ID. Can be specified multiple times to filter on more than one ID.
resourceType	string Enum: "InstanceType" "IPBlock" Filter Allocations by Constraint Resource Type. Can be specified multiple times to filter on more than one Constraint Resource Type.
status	string Filter Allocations by Status. Can be specified multiple times to filter on more than one Status.
resourceTypeId	string Filter Allocations by Constraint Resource Type ID. Can be specified multiple times to filter on more than one Constraint Resource Type ID.
constraintType	string Enum: "Reserved" "OnDemand" "Preemptible" Filter Allocations by Constraint Type. Can be specified multiple times to filter on more than one Constraint Type.
constraintValue	integer Filter Allocations by Constraint Value. Can be specified multiple times to filter on more than one Constraint Value.
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "SITE_NAME_ASC" "SITE_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "INSTANCE_TYPE_NAME_ASC" "INSTANCE_TYPE_NAME_DESC" "IP_BLOCK_NAME_ASC" "IP_BLOCK_NAME_DESC" "CONSTRAINT_VALUE_ASC" "CONSTRAINT_VALUE_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> ID of the Allocation
name	string [ 2 .. 256 ] characters Concise and descriptive name of the Allocation
description	string Detailed description of the Allocation
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that created the Allocation
tenantId	string <uuid> ID of the Tenant that received the Allocation
siteId	string <uuid> ID of the Site where resources are allocated
status	string (AllocationStatus) Enum: "Pending" "Registered" "Deleting" "Error" Status values for Allocation objects
	Array of objects (StatusDetail)
	Array of objects (AllocationConstraint)
created	string <date-time> Date/time when the Allocation was created
updated	string <date-time> Date/time when the Allocation was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Echo Studios",
"description": "Echo Studios resource allocation in SJC4",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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",
"allocationConstraints": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]
}
]

Create Allocation

Create an Allocation for the org.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Tenant management of Allocation is not supported in MVP.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Concise and descriptive name for the Allocation
description	string Detailed description for the Allocation
tenantId required	string <uuid> ID of the Tenant that should receive the Allocation
siteId required	string <uuid> ID of the Site where resources should be allocated
	Array of objects (AllocationConstraintCreateRequest)

Responses

Response Schema: application/json

id	string <uuid> ID of the Allocation
name	string [ 2 .. 256 ] characters Concise and descriptive name of the Allocation
description	string Detailed description of the Allocation
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that created the Allocation
tenantId	string <uuid> ID of the Tenant that received the Allocation
siteId	string <uuid> ID of the Site where resources are allocated
status	string (AllocationStatus) Enum: "Pending" "Registered" "Deleting" "Error" Status values for Allocation objects
	Array of objects (StatusDetail)
	Array of objects (AllocationConstraint)
created	string <date-time> Date/time when the Allocation was created
updated	string <date-time> Date/time when the Allocation was last updated

Request samples

Payload

Content type

application/json

{"name": "Echo Studios",
"description": "Echo Studios resource allocation in SJC4",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"allocationConstraints": [{"resourceType": "InstanceType",
"resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
"constraintType": "Reserved",
"constraintValue": 10
}
]
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Echo Studios",
"description": "Echo Studios resource allocation in SJC4",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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",
"allocationConstraints": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]
}

Retrieve Allocation

Retrieve Allocation by ID

Provider and Tenant roles are inferred from the org's membership. Allocation must belong to the Provider or Tenant associated with the org.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string <uuid> ID of the Allocation

query Parameters

infrastructureProviderId	string <uuid> Deprecated Filter Allocations by Infrastructure Provider ID.
tenantId	string <uuid> Deprecated Filter Allocations by Tenant ID.
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> ID of the Allocation
name	string [ 2 .. 256 ] characters Concise and descriptive name of the Allocation
description	string Detailed description of the Allocation
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that created the Allocation
tenantId	string <uuid> ID of the Tenant that received the Allocation
siteId	string <uuid> ID of the Site where resources are allocated
status	string (AllocationStatus) Enum: "Pending" "Registered" "Deleting" "Error" Status values for Allocation objects
	Array of objects (StatusDetail)
	Array of objects (AllocationConstraint)
created	string <date-time> Date/time when the Allocation was created
updated	string <date-time> Date/time when the Allocation was last updated

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Echo Studios",
"description": "Echo Studios resource allocation in SJC4",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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",
"allocationConstraints": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]
}

Delete Allocation

Delete an Allocation by ID.

Org must have an Infrastructure Provider entity, specified Allocation must be created by said Provider. Requesting user must have FORGE_PROVIDER_ADMIN role.

Tenant management of Allocation is not supported in MVP.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string <uuid> ID of the Allocation

Responses

Update Allocation

Update an existing Allocation

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role. Provider must own the Allocation.

Tenant management of Allocation is not supported in MVP.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string <uuid> ID of the Allocation

Request Body schema: application/json

name	string [ 2 .. 256 ] characters Update name of the Allocation
description	string Update description of the Allocation

Responses

Response Schema: application/json

id	string <uuid> ID of the Allocation
name	string [ 2 .. 256 ] characters Concise and descriptive name of the Allocation
description	string Detailed description of the Allocation
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that created the Allocation
tenantId	string <uuid> ID of the Tenant that received the Allocation
siteId	string <uuid> ID of the Site where resources are allocated
status	string (AllocationStatus) Enum: "Pending" "Registered" "Deleting" "Error" Status values for Allocation objects
	Array of objects (StatusDetail)
	Array of objects (AllocationConstraint)
created	string <date-time> Date/time when the Allocation was created
updated	string <date-time> Date/time when the Allocation was last updated

Request samples

Payload

Content type

application/json

{"name": "Echo Studios Compute",
"description": "Echo Studios compute resource allocation in SJC4"
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Echo Studios Compute",
"description": "Echo Studios compute resource allocation in SJC4",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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",
"allocationConstraints": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]
}

Retrieve all Allocation Constraints

Retrieve all Allocation Constraints for a given Allocation ID.

If org has an Infrastructure Provider entity, then specified Allocation must have been created by the Provider and requesting user must have FORGE_PROVIDER_ADMIN role.

If org does not have an Infrastructure Provider entity but has a Tenant entity, then specified Allocation must belong to the Tenant and requesting user must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string <uuid> ID of the Allocation

query Parameters

pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "RESOURCE_TYPE_ASC" "RESOURCE_TYPE_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> ID of the Allocation Constraint
allocationId	string <uuid> ID of the Allocation that contains the Allocation Constraint
resourceType	string Enum: "InstanceType" "IPBlock" Type of the Resource that the Allocation Constraint applies to
resourceTypeId	string <uuid> ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.
constraintType	string Enum: "Reserved" "OnDemand" "Preemptible" Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.
constraintValue	integer Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.
derivedResourceId	string or null ID of the allocated Tenant IP Block when resource type is IPBlock
	object (InstanceTypeSummary) Describes a subset of core attributes of an Instance Type
	object (IpBlockSummary) Describes a subset of core attributes of an IP block
created	string <date-time> Date/time when the Allocation Constraint was created
updated	string <date-time> Date/time when the Allocation Constraint was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create Allocation Constraint

Create an Allocation Constraint for a given Allocation ID.

Org must have an Infrastructure Provider entity and specified Allocation must have been created by the Provider. User must have FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string <uuid> ID of the Allocation

Request Body schema: application/json

resourceType required	string Enum: "InstanceType" "IPBlock" Type of the Resource that the Allocation Constraint applies to
resourceTypeId required	string <uuid> ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.
constraintType required	string Enum: "Reserved" "OnDemand" "Preemptible" Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.
constraintValue required	integer Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

Responses

Response Schema: application/json

id	string <uuid> ID of the Allocation Constraint
allocationId	string <uuid> ID of the Allocation that contains the Allocation Constraint
resourceType	string Enum: "InstanceType" "IPBlock" Type of the Resource that the Allocation Constraint applies to
resourceTypeId	string <uuid> ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.
constraintType	string Enum: "Reserved" "OnDemand" "Preemptible" Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.
constraintValue	integer Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.
derivedResourceId	string or null ID of the allocated Tenant IP Block when resource type is IPBlock
	object (InstanceTypeSummary) Describes a subset of core attributes of an Instance Type
	object (IpBlockSummary) Describes a subset of core attributes of an IP block
created	string <date-time> Date/time when the Allocation Constraint was created
updated	string <date-time> Date/time when the Allocation Constraint was last updated

Request samples

Payload

Content type

application/json

{"resourceType": "InstanceType",
"resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
"constraintType": "Reserved",
"constraintValue": 10
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve Allocation Constraint

Retrieve an Allocation Constraint for a given Allocation ID.

If org has an Infrastructure Provider entity, then specified Allocation must have been created by the Provider and requesting user must have FORGE_PROVIDER_ADMIN role.

If org does not have an Infrastructure Provider entity but has a Tenant entity, then specified Allocation must belong to the Tenant and requesting user must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string ID of the Allocation
allocationConstraintId required	string <uuid> ID of the Allocation Constraint

Responses

Response Schema: application/json

Array

id	string <uuid> ID of the Allocation Constraint
allocationId	string <uuid> ID of the Allocation that contains the Allocation Constraint
resourceType	string Enum: "InstanceType" "IPBlock" Type of the Resource that the Allocation Constraint applies to
resourceTypeId	string <uuid> ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.
constraintType	string Enum: "Reserved" "OnDemand" "Preemptible" Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.
constraintValue	integer Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.
derivedResourceId	string or null ID of the allocated Tenant IP Block when resource type is IPBlock
	object (InstanceTypeSummary) Describes a subset of core attributes of an Instance Type
	object (IpBlockSummary) Describes a subset of core attributes of an IP block
created	string <date-time> Date/time when the Allocation Constraint was created
updated	string <date-time> Date/time when the Allocation Constraint was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 10,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Update Allocation Constraint

Update an existing Allocation Constraint by ID

Org must have an Infrastructure Provider. Specified Allocation must have been created by the Provider and requesting user must have FORGE_PROVIDER_ADMIN role.

Modifying allocations may not be possible if Tenant has started utilizing resources from this allocation.

In case of InstanceType resource, constraintValue can be incremented anytime, but not decremented if it requires decommissioning Tenant resources.

In case of IPBlock resource, constraintValue can not be modified if Tenant resources are using IPs from the block.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string ID of the Allocation
allocationConstraintId required	string <uuid> ID of the Allocation Constraint

Request Body schema: application/json

constraintValue

required

integer

Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

Responses

Response Schema: application/json

id	string <uuid> ID of the Allocation Constraint
allocationId	string <uuid> ID of the Allocation that contains the Allocation Constraint
resourceType	string Enum: "InstanceType" "IPBlock" Type of the Resource that the Allocation Constraint applies to
resourceTypeId	string <uuid> ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.
constraintType	string Enum: "Reserved" "OnDemand" "Preemptible" Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.
constraintValue	integer Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.
derivedResourceId	string or null ID of the allocated Tenant IP Block when resource type is IPBlock
	object (InstanceTypeSummary) Describes a subset of core attributes of an Instance Type
	object (IpBlockSummary) Describes a subset of core attributes of an IP block
created	string <date-time> Date/time when the Allocation Constraint was created
updated	string <date-time> Date/time when the Allocation Constraint was last updated

Request samples

Payload

Content type

application/json

{"constraintValue": 20
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
"resourceType": "InstanceType",
"resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
"constraintType": "Reserved",
"constraintValue": 20,
"derivedResourceId": null,
"instanceType": {"name": "x3.large",
"infrastructureProviderId": "63c29416-8833-4eaf-9e1c-7c0173cc3150",
"siteId": "c9f4f276-6f7a-4209-953c-2b9870ce7cc1",
"status": "Ready"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Allocation Constraint

Delete an existing Allocation Constraint by ID

Org must have an Infrastructure Provider. Specified Allocation must have been created by the Provider and requesting user must have FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
allocationId required	string ID of the Allocation
allocationConstraintId required	string <uuid> ID of the Allocation Constraint

Responses

VPC

VPC defines the networking isolation boundary for Tenant's Instances.

Retrieve all VPCs

Retrieve all VPCs for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter VPCs by Site ID. Can be specified multiple times to filter on more than one Site.
status	string Filter VPCs by Status. Can be specified multiple times to filter on more than one Status.
networkSecurityGroupId	string Filter VPCs by Network Security Group ID. Can be specified multiple times to filter on more than one Network Security Group.
nvLinkLogicalPartitionId	string <uuid> Filter VPCs by NVLink Logical Partition ID. Can be specified multiple times to filter on more than one NVLink Logical Partition.
query	string Search for matches across all VPCs. Input will be matched against name, description, labels and status fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> ID of the VPC
name	string [ 2 .. 256 ] characters Name of the VPC
description	string Description of the VPC, can be empty
org	string Organization the VPC belongs to
tenantId	string <uuid> ID of the Tenant the VPC belongs to
siteId	string <uuid> ID of the Site the VPC belongs to
controllerVpcId	string or null <uuid> Legacy attribute, contains the same value as ID
networkVirtualizationType	string Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC
routingProfile	string or null [ 3 .. 64 ] characters Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is `FNN`.
requestedVni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC if one was requested at creation time
vni	integer or null [ 1 .. 65535 ] Active VNI assigned to the VPC
networkSecurityGroupId	string or null ID of the Network Security Group attached to the VPC
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels
status	string (VpcStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status of the VPC
	Array of objects (StatusDetail) History of status changes for the VPC
created	string <date-time> Date/time when VPC was created
updated	string <date-time> Date/time when VPC was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc",
"description": "Virtual network for machines executing Spark jobs",
"org": "xskkpgqpeakn",
"tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"networkVirtualizationType": "ETHERNET_VIRTUALIZER",
"requestedVni": 12001,
"vni": 12001,
"networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e",
"networkSecurityGroupPropagationDetails": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"detailedStatus": "Partial",
"status": "Synchronizing",
"details": "",
"unpropagatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"relatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
},
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Vpc has been successfully provisioned on Site",
"created": "2019-08-24T16:02:00Z",
"updated": "2019-08-24T16:02:00Z"
},
{"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"
}
]

Create VPC

Create a VPC for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

id	string <uuid> Optional user-specified UUID for the VPC
name required	string [ 2 .. 256 ] characters Name of the VPC
description	string Optional description for the VPC
siteId required	string <uuid> ID of the Site where the VPC should be created
networkVirtualizationType	string or null Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC. If no value is specified, then defaults to `FNN` if Site has native networking enabled, or ETHERNET_VIRTUALIZER if native networking is disabled
routingProfile	string or null [ 3 .. 64 ] characters Specify routing profile for the VPC. Only supported when `networkVirtualizationType` is set to `FNN`, or when `networkVirtualizationType` is omitted and Site has Native Networking enabled. Requires Tenant to have elevated privilege. Current accepted values are `privileged-internal`, `internal`, and `external`.
networkSecurityGroupId	string or null ID of the Network Security Group to attach to the VPC
vni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels. Up to 10 key value pairs can be specified

Responses

Response Schema: application/json

id	string <uuid> ID of the VPC
name	string [ 2 .. 256 ] characters Name of the VPC
description	string Description of the VPC, can be empty
org	string Organization the VPC belongs to
tenantId	string <uuid> ID of the Tenant the VPC belongs to
siteId	string <uuid> ID of the Site the VPC belongs to
controllerVpcId	string or null <uuid> Legacy attribute, contains the same value as ID
networkVirtualizationType	string Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC
routingProfile	string or null [ 3 .. 64 ] characters Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is `FNN`.
requestedVni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC if one was requested at creation time
vni	integer or null [ 1 .. 65535 ] Active VNI assigned to the VPC
networkSecurityGroupId	string or null ID of the Network Security Group attached to the VPC
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels
status	string (VpcStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status of the VPC
	Array of objects (StatusDetail) History of status changes for the VPC
created	string <date-time> Date/time when VPC was created
updated	string <date-time> Date/time when VPC was last updated

Request samples

Payload

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc",
"description": "Virtual network for machines executing Spark jobs",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"networkVirtualizationType": "ETHERNET_VIRTUALIZER",
"vni": 12001,
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc",
"description": "Virtual network for machines executing Spark jobs",
"org": "xskkpgqpeakn",
"tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"networkVirtualizationType": "ETHERNET_VIRTUALIZER",
"requestedVni": 12001,
"vni": 12001,
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
},
"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"
}

Retrieve a VPC

Retrieve a specific VPC by ID.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcId required	string <uuid> ID of the VPC

query Parameters

includeRelation

string

Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> ID of the VPC
name	string [ 2 .. 256 ] characters Name of the VPC
description	string Description of the VPC, can be empty
org	string Organization the VPC belongs to
tenantId	string <uuid> ID of the Tenant the VPC belongs to
siteId	string <uuid> ID of the Site the VPC belongs to
controllerVpcId	string or null <uuid> Legacy attribute, contains the same value as ID
networkVirtualizationType	string Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC
routingProfile	string or null [ 3 .. 64 ] characters Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is `FNN`.
requestedVni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC if one was requested at creation time
vni	integer or null [ 1 .. 65535 ] Active VNI assigned to the VPC
networkSecurityGroupId	string or null ID of the Network Security Group attached to the VPC
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels
status	string (VpcStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status of the VPC
	Array of objects (StatusDetail) History of status changes for the VPC
created	string <date-time> Date/time when VPC was created
updated	string <date-time> Date/time when VPC was last updated

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc",
"description": "Virtual network for machines executing Spark jobs",
"org": "xskkpgqpeakn",
"tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"networkVirtualizationType": "ETHERNET_VIRTUALIZER",
"requestedVni": 12001,
"vni": 12001,
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
},
"status": "Ready",
"networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e,",
"networkSecurityGroupPropagationDetails": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"detailedStatus": "Partial",
"status": "Synchronizing",
"details": "",
"unpropagatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"relatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"statusHistory": [{"status": "Ready",
"message": "Vpc has been successfully provisioned on Site",
"created": "2019-08-24T16:02:00Z",
"updated": "2019-08-24T16:02:00Z"
},
{"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"
}

Delete a VPC

Delete a specific VPC by ID.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcId required	string <uuid> ID of the VPC

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update VPC

Update an existing VPC

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcId required	string <uuid> ID of the VPC

Request Body schema: application/json

name	string [ 2 .. 256 ] characters Updated name of the VPC
description	string Updated description of the VPC
networkSecurityGroupId	string or null ID of the Network Security Group to attach to the VPC
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to. Can only be updated if VPC currently has no active Instances
	object (Labels) <= 10 properties Update labels of the VPC. Up to 10 key value pairs can be specified. The labels will be entirely replaced by those sent in the request. Any labels not included in the request will be removed. To retain existing labels, first fetch them and include them along with this request.

Responses

Response Schema: application/json

id	string <uuid> ID of the VPC
name	string [ 2 .. 256 ] characters Name of the VPC
description	string Description of the VPC, can be empty
org	string Organization the VPC belongs to
tenantId	string <uuid> ID of the Tenant the VPC belongs to
siteId	string <uuid> ID of the Site the VPC belongs to
controllerVpcId	string or null <uuid> Legacy attribute, contains the same value as ID
networkVirtualizationType	string Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC
routingProfile	string or null [ 3 .. 64 ] characters Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is `FNN`.
requestedVni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC if one was requested at creation time
vni	integer or null [ 1 .. 65535 ] Active VNI assigned to the VPC
networkSecurityGroupId	string or null ID of the Network Security Group attached to the VPC
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels
status	string (VpcStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status of the VPC
	Array of objects (StatusDetail) History of status changes for the VPC
created	string <date-time> Date/time when VPC was created
updated	string <date-time> Date/time when VPC was last updated

Request samples

Payload

Content type

application/json

{"name": "spark-vpc-v1",
"description": "Virtual network for machines executing Spark jobs v1",
"labels": {"region": "us-west-1",
"env": "dev"
}
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc-v1",
"description": "Virtual network for machines executing Spark jobs v1",
"org": "xskkpgqpeakn",
"tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"networkVirtualizationType": "ETHERNET_VIRTUALIZER",
"requestedVni": 12001,
"vni": 12001,
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
},
"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"
}

Update VPC Virtualization

Update network virtualization type for a VPC

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role

Tenant must own the VPC Request is rejected if the VPC already has Subnets or Instances

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcId required	string <uuid> ID of the VPC

Request Body schema: application/json

networkVirtualizationType

string

Value: "FNN"

Network virtualization type of the VPC. Can only be updated to FNN

Responses

Response Schema: application/json

id	string <uuid> ID of the VPC
name	string [ 2 .. 256 ] characters Name of the VPC
description	string Description of the VPC, can be empty
org	string Organization the VPC belongs to
tenantId	string <uuid> ID of the Tenant the VPC belongs to
siteId	string <uuid> ID of the Site the VPC belongs to
controllerVpcId	string or null <uuid> Legacy attribute, contains the same value as ID
networkVirtualizationType	string Enum: "ETHERNET_VIRTUALIZER" "FNN" Network virtualization type of the VPC
routingProfile	string or null [ 3 .. 64 ] characters Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is `FNN`.
requestedVni	integer or null [ 1 .. 65535 ] Explicitly requested VNI for the VPC if one was requested at creation time
vni	integer or null [ 1 .. 65535 ] Active VNI assigned to the VPC
networkSecurityGroupId	string or null ID of the Network Security Group attached to the VPC
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
nvLinkLogicalPartitionId	string or null <uuid> ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to
	object (Labels) <= 10 properties String key value pairs describing VPC labels
status	string (VpcStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status of the VPC
	Array of objects (StatusDetail) History of status changes for the VPC
created	string <date-time> Date/time when VPC was created
updated	string <date-time> Date/time when VPC was last updated

Request samples

Payload

Content type

application/json

{"networkVirtualizationType": "FNN"
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-vpc-v1",
"description": "Virtual network for machines executing Spark jobs v1",
"org": "xskkpgqpeakn",
"tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"networkVirtualizationType": "FNN",
"requestedVni": 12001,
"vni": 12001,
"nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
"labels": {"region": "us-west-1",
"env": "dev"
},
"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"
}

VPC Peering

VPC Peering allows Instances in one VPC to communicate with Instances in another VPC on the same Site.

Retrieve all VPC peerings

Get all VPC peerings. Tenant Admin can get all peerings where the tenant owns at least one VPC. Provider Admin can get all peerings in a site. User must have FORGE_TENANT_ADMIN or FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Optional Site ID filter. If provided, caller must have access to the specified Site.
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Ordering for pagination query
isMultiTenant	boolean Optional filter by peering tenancy type (single-tenant or multi-tenant).
includeRelation	string Enum: "Vpc1" "Vpc2" "Site" Related entity to expand

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier of the VPC peering
vpc1Id	string <uuid> ID of the first VPC in the peering
vpc2Id	string <uuid> ID of the second VPC in the peering
siteId	string <uuid> ID of the Site where the peering exists
isMultiTenant	boolean Indicates if this is a multi-tenant peering (VPCs from different tenants)
status	string (VpcPeeringStatus) Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error" Status of the VPC peering
created	string <date-time> Date and time when the VPC peering was created
updated	string <date-time> Date and time when the VPC peering was last updated

Response samples

200
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
"vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"isMultiTenant": true,
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create VPC peering

Create a VPC peering between two VPCs on the same site.

Tenant Admin can create single-tenant peerings (both VPCs belong to their tenant). Provider Admin can create multi-tenant peerings (VPCs from different tenants).

User must have FORGE_TENANT_ADMIN or FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

vpc1Id required	string <uuid> ID of the first VPC in the peering
vpc2Id required	string <uuid> ID of the second VPC to peer with
siteId required	string <uuid> ID of the Site where the peering exists

Responses

Response Schema: application/json

id	string <uuid> Unique identifier of the VPC peering
vpc1Id	string <uuid> ID of the first VPC in the peering
vpc2Id	string <uuid> ID of the second VPC in the peering
siteId	string <uuid> ID of the Site where the peering exists
isMultiTenant	boolean Indicates if this is a multi-tenant peering (VPCs from different tenants)
status	string (VpcPeeringStatus) Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error" Status of the VPC peering
created	string <date-time> Date and time when the VPC peering was created
updated	string <date-time> Date and time when the VPC peering was last updated

Request samples

Payload

Content type

application/json

{"vpc1Id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"vpc2Id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811"
}

Response samples

201
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
"vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"isMultiTenant": true,
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve a VPC peering

Get details of a VPC peering by ID.

Tenant Admin can get a peering if at least one VPC belongs to their tenant. Provider Admin can get a peering if it is in a site provided by their org.

User must have FORGE_TENANT_ADMIN or FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> VPC Peering ID

query Parameters

includeRelation

string

Enum: "Vpc1" "Vpc2" "Site"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique identifier of the VPC peering
vpc1Id	string <uuid> ID of the first VPC in the peering
vpc2Id	string <uuid> ID of the second VPC in the peering
siteId	string <uuid> ID of the Site where the peering exists
isMultiTenant	boolean Indicates if this is a multi-tenant peering (VPCs from different tenants)
status	string (VpcPeeringStatus) Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error" Status of the VPC peering
created	string <date-time> Date and time when the VPC peering was created
updated	string <date-time> Date and time when the VPC peering was last updated

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
"vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"isMultiTenant": true,
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete a VPC peering

Delete a VPC peering by ID.

Tenant Admin can delete only peerings where both VPCs belong to their tenant. Provider Admin can delete only multi-tenant peerings in sites they provide.

User must have FORGE_TENANT_ADMIN or FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> VPC Peering ID

Responses

Response samples

400
403
404

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

VPC Prefix

VPC Prefix is a network prefix belonging to an IP Block allocated to a Tenant. Tenant can use VPC Prefixes to enable network connectivity between their Instances.

Only Sites that support Native Networking (FNN) offer VPC Prefix management.

Retrieve all VPC Prefixes

Retrieve all VPC Prefixes for the org

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter VPC Prefixes by Site, required if vpcId query param is not specified
vpcId	string <uuid> Filter VPC Prefixes by VPC
status	string Filter VPC Prefixes by Status
query	string Search for matches across all Sites. Input will be matched against name and status fields
includeRelation	string Enum: "VPC" "Tenant" "IPBlock" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the VPC Prefix
siteId	string <uuid> ID of the Site the VPC Prefix belongs to
vpcId	string <uuid> ID of the VPC the VPC Prefix belongs to
tenantId	string <uuid> ID of the Tenant the VPC Prefix belongs to
ipBlockId	string or null <uuid> ID of the IP Block that contains the prefix of the VPC Prefix
prefix	string or null The network prefix including prefix length in CIDR notation
prefixLength	integer [ 8 .. 31 ] Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.
status	string (VpcPrefixStatus) Enum: "Ready" "Deleting" "Error" Status of the VPC Prefix
	Array of objects (StatusDetail) Details of 20 most recent status changes
created	string <date-time> Date and time when the VPC Prefix was created
updated	string <date-time> Date and time when the VPC Prefix was updated

Response samples

200
403

Content type

application/json

[{"id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
"name": "east-vpc-traffic-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"prefix": "192.168.1.0/24",
"ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Received VPC prefix creation request, ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create VPC Prefix

Create a VPC Prefix for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Human readable name for the VPC Prefix
vpcId required	string <uuid> ID of the VPC
ipBlockId required	string <uuid> ID of the IP Block to allocate the VPC Prefix from
prefixLength required	integer [ 8 .. 31 ] Prefix length for the VPC Prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the VPC Prefix
siteId	string <uuid> ID of the Site the VPC Prefix belongs to
vpcId	string <uuid> ID of the VPC the VPC Prefix belongs to
tenantId	string <uuid> ID of the Tenant the VPC Prefix belongs to
ipBlockId	string or null <uuid> ID of the IP Block that contains the prefix of the VPC Prefix
prefix	string or null The network prefix including prefix length in CIDR notation
prefixLength	integer [ 8 .. 31 ] Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.
status	string (VpcPrefixStatus) Enum: "Ready" "Deleting" "Error" Status of the VPC Prefix
	Array of objects (StatusDetail) Details of 20 most recent status changes
created	string <date-time> Date and time when the VPC Prefix was created
updated	string <date-time> Date and time when the VPC Prefix was updated

Request samples

Payload

Content type

application/json

{"name": "east-vpc-traffic-net",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20
}

Response samples

201
400
403

Content type

application/json

{"id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
"name": "east-vpc-traffic-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"prefix": "192.168.1.0/24",
"ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Received VPC prefix creation request, ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve VPC Prefix

Retrieve a specific VPC Prefix

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcPrefixId required	string <uuid> ID of the VPC Prefix

query Parameters

includeRelation

string

Enum: "VPC" "Tenant" "IPBlock"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the VPC Prefix
siteId	string <uuid> ID of the Site the VPC Prefix belongs to
vpcId	string <uuid> ID of the VPC the VPC Prefix belongs to
tenantId	string <uuid> ID of the Tenant the VPC Prefix belongs to
ipBlockId	string or null <uuid> ID of the IP Block that contains the prefix of the VPC Prefix
prefix	string or null The network prefix including prefix length in CIDR notation
prefixLength	integer [ 8 .. 31 ] Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.
status	string (VpcPrefixStatus) Enum: "Ready" "Deleting" "Error" Status of the VPC Prefix
	Array of objects (StatusDetail) Details of 20 most recent status changes
created	string <date-time> Date and time when the VPC Prefix was created
updated	string <date-time> Date and time when the VPC Prefix was updated

Response samples

200
403

Content type

application/json

{"id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
"name": "east-vpc-traffic-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"prefix": "192.168.1.0/24",
"ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Received VPC prefix creation request, ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete VPC Prefix

Delete a specific VPC Prefix by ID.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcPrefixId required	string <uuid> ID of the VPC Prefix

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update VPC Prefix

Update an existing VPC Prefix

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
vpcPrefixId required	string <uuid> ID of the VPC Prefix

Request Body schema: application/json

name

required

string [ 2 .. 256 ] characters

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters Name of the VPC Prefix
siteId	string <uuid> ID of the Site the VPC Prefix belongs to
vpcId	string <uuid> ID of the VPC the VPC Prefix belongs to
tenantId	string <uuid> ID of the Tenant the VPC Prefix belongs to
ipBlockId	string or null <uuid> ID of the IP Block that contains the prefix of the VPC Prefix
prefix	string or null The network prefix including prefix length in CIDR notation
prefixLength	integer [ 8 .. 31 ] Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.
status	string (VpcPrefixStatus) Enum: "Ready" "Deleting" "Error" Status of the VPC Prefix
	Array of objects (StatusDetail) Details of 20 most recent status changes
created	string <date-time> Date and time when the VPC Prefix was created
updated	string <date-time> Date and time when the VPC Prefix was updated

Request samples

Payload

Content type

application/json

{"name": "east-vpc-traffic-net"
}

Response samples

200
400
403

Content type

application/json

{"id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
"name": "east-vpc-traffic-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"prefix": "192.168.1.0/24",
"ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20,
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Received VPC prefix creation request, ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Subnet

Subnet is a network prefix belonging to an IP Block allocated to a Tenant. Tenant can use Subnets to enable network connectivity between their Instances.

Subnets are used on Sites that do not support Native Networking (FNN).

Deprecation history:

ipBlockSize was deprecated in favor of prefixLength and was removed on April 15th, 2023 0:00 UTC. Please use prefixLength instead.

Retrieve all Subnets

Retrieve all Subnets for the org

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter subnets by Site, required if vpcId query param is not specified
vpcId	string <uuid> Filter subnets by VPC
status	string Filter Subnets by Status
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
vpcId	string <uuid>
tenantId	string <uuid>
controllerNetworkSegmentId	string or null <uuid>
ipv4Prefix	string or null <ipv4> The prefix that gets assigned to the subnet if ipv4 block is chosen
ipv4BlockId	string or null <uuid>
ipv4Gateway	string or null <ipv4>
ipv6Prefix	string or null <ipv6>
ipv6BlockId	string or null <uuid>
ipv6Gateway	string or null <ipv6>
mtu	integer Maximum Transmission Unit size in bytes. This property is system-determined and read-only.
prefixLength	integer Max value depends on prefix length of parent IP Block
routingType	string Enum: "Public" "DatacenterOnly"
status	string (SubnetStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Subnet objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	Array of objects (Deprecation)

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-gpu-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerNetworkSegmentId": "abe7b0e8-67db-4e89-903e-fc4f2bd7f034",
"ipv4Prefix": "202.168.16.0",
"ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"ipv4Gateway": "202.168.0.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"prefixLength": 20,
"routingType": "Public",
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Subnet has been successfully provisioned on Site",
"created": "2019-08-24T16:02:38Z",
"updated": "2019-08-24T16:02:38Z"
},
{"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"
}
]

Create Subnet

Create a Subnet for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

At least 1 IPv4 IP block or 1 IPv6 IP block must be specified.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string
vpcId required	string <uuid>
ipv4BlockId	string <uuid>
ipv6BlockId	string <uuid>
prefixLength required	integer

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
vpcId	string <uuid>
tenantId	string <uuid>
controllerNetworkSegmentId	string or null <uuid>
ipv4Prefix	string or null <ipv4> The prefix that gets assigned to the subnet if ipv4 block is chosen
ipv4BlockId	string or null <uuid>
ipv4Gateway	string or null <ipv4>
ipv6Prefix	string or null <ipv6>
ipv6BlockId	string or null <uuid>
ipv6Gateway	string or null <ipv6>
mtu	integer Maximum Transmission Unit size in bytes. This property is system-determined and read-only.
prefixLength	integer Max value depends on prefix length of parent IP Block
routingType	string Enum: "Public" "DatacenterOnly"
status	string (SubnetStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Subnet objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	Array of objects (Deprecation)

Request samples

Payload

Content type

application/json

{"name": "spark-gpu-net",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"prefixLength": 20
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-gpu-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerNetworkSegmentId": null,
"ipv4Prefix": "202.168.16.0",
"ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"ipv4Gateway": "202.168.0.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"prefixLength": 20,
"routingType": "Public",
"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"
}

Retrieve Subnet

Retrieve a specific Subnet

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
subnetId required	string <uuid> ID of the Subnet

query Parameters

includeRelation

string

Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
vpcId	string <uuid>
tenantId	string <uuid>
controllerNetworkSegmentId	string or null <uuid>
ipv4Prefix	string or null <ipv4> The prefix that gets assigned to the subnet if ipv4 block is chosen
ipv4BlockId	string or null <uuid>
ipv4Gateway	string or null <ipv4>
ipv6Prefix	string or null <ipv6>
ipv6BlockId	string or null <uuid>
ipv6Gateway	string or null <ipv6>
mtu	integer Maximum Transmission Unit size in bytes. This property is system-determined and read-only.
prefixLength	integer Max value depends on prefix length of parent IP Block
routingType	string Enum: "Public" "DatacenterOnly"
status	string (SubnetStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Subnet objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	Array of objects (Deprecation)

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-gpu-net",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerNetworkSegmentId": "abe7b0e8-67db-4e89-903e-fc4f2bd7f034",
"ipv4Prefix": "202.168.16.0",
"ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"ipv4Gateway": "202.168.0.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"prefixLength": 20,
"routingType": "Public",
"status": "Ready",
"statusHistory": [{"status": "Ready",
"message": "Subnet has been successfully provisioned on Site",
"created": "2019-08-24T16:02:38Z",
"updated": "2019-08-24T16:02:38Z"
},
{"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"
}

Delete Subnet

Delete a specific Subnet by ID.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
subnetId required	string <uuid> ID of the Subnet

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update Subnet

Update an existing Subnet

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
subnetId required	string <uuid> ID of the Subnet

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
vpcId	string <uuid>
tenantId	string <uuid>
controllerNetworkSegmentId	string or null <uuid>
ipv4Prefix	string or null <ipv4> The prefix that gets assigned to the subnet if ipv4 block is chosen
ipv4BlockId	string or null <uuid>
ipv4Gateway	string or null <ipv4>
ipv6Prefix	string or null <ipv6>
ipv6BlockId	string or null <uuid>
ipv6Gateway	string or null <ipv6>
mtu	integer Maximum Transmission Unit size in bytes. This property is system-determined and read-only.
prefixLength	integer Max value depends on prefix length of parent IP Block
routingType	string Enum: "Public" "DatacenterOnly"
status	string (SubnetStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Subnet objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>
	Array of objects (Deprecation)

Request samples

Payload

Content type

application/json

{"name": "spark-gpu-subnet",
"description": "Subnet for dedicated GPU nodes"
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-gpu-subnet",
"description": "Subnet for dedicated GPU nodes",
"siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerNetworkSegmentId": null,
"ipv4Prefix": "212.168.0.250",
"ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
"ipv4Gateway": "202.168.0.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"prefixLength": 20,
"routingType": "Public",
"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"
}

Expected Machine

Expected Machine identifies a Machine that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Machines using BMC credentials and serial numbers to help with Machine discovery and ingestion.

Create Expected Machine

Create an Expected Machine to pre-register Machines expected to be discovered at a Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Machines if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

Expected Machine creation request

siteId required	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress required	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 20 characters Username for accessing the Expected Machine's BMC
defaultBmcPassword	string or null <= 50 characters Password for accessing the Expected Machine's BMC
chassisSerialNumber required	string [ 1 .. 100 ] characters Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings or null Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU to associate with this Expected Machine
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Request samples

Payload

Content type

application/json

{"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"defaultBmcUsername": "admin",
"defaultBmcPassword": "password123",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"labels": {"environment": "production",
"rack": "A1"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve all Expected Machines

Retrieve all Expected Machines.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Machines if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> ID of the Site to filter Expected Machines by
includeRelation	string Enum: "Site" "Sku" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "CHASSIS_SERIAL_NUMBER_ASC" "CHASSIS_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Response samples

200
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve Expected Machine

Retrieve a specific Expected Machine by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Machines if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedMachineId required	string ID of the Expected Machine

query Parameters

includeRelation

string

Enum: "Site" "Sku"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Update Expected Machine

Update an existing Expected Machine by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Machine.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Machines if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedMachineId required	string ID of the Expected Machine

Request Body schema: application/json
required

Expected Machine update request

id	string or null <uuid> ID of the Expected Machine to update. Optional for individual Expected Machine update (ignored if provided, ID from URL path is used). Required for batch update operations.
bmcMacAddress	string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 20 characters Username for accessing the Expected Machine's BMC
defaultBmcPassword	string or null <= 50 characters Password for accessing the Expected Machine's BMC
chassisSerialNumber	string or null [ 1 .. 100 ] characters Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings or null Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU to associate with this Expected Machine
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Request samples

Payload

Content type

application/json

{"defaultBmcUsername": "newadmin",
"defaultBmcPassword": "newpassword123",
"chassisSerialNumber": "CHASSIS-54321",
"labels": {"environment": "staging",
"rack": "B2"
}
}

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Expected Machine

Delete an existing Expected Machine by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Machine.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Machines if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedMachineId required	string ID of the Expected Machine

Responses

Response samples

400
403
404

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

Batch Create Expected Machines

Create multiple Expected Machines in a single request. All machines must belong to the same site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Machines if they have an account with the Site's Infrastructure Provider.

Maximum batch size: 100 Expected Machines per request.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

Array of Expected Machine creation requests

Array ([ 1 .. 100 ] items)

siteId required	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress required	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 20 characters Username for accessing the Expected Machine's BMC
defaultBmcPassword	string or null <= 50 characters Password for accessing the Expected Machine's BMC
chassisSerialNumber required	string [ 1 .. 100 ] characters Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings or null Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU to associate with this Expected Machine
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Request samples

Payload

Content type

application/json

[{"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"defaultBmcUsername": "admin",
"defaultBmcPassword": "password123",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"labels": {"environment": "production",
"rack": "A1"
}
},
{"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5F",
"defaultBmcUsername": "admin",
"defaultBmcPassword": "password456",
"chassisSerialNumber": "CHASSIS-12346",
"fallbackDPUSerialNumbers": ["DPU-003",
"DPU-004"
],
"labels": {"environment": "production",
"rack": "A2"
}
}
]

Response samples

201
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Batch Update Expected Machines

Update multiple Expected Machines in a single request. All machines must belong to the same site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Machines.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Machines if they have an account with the Site's Infrastructure Provider.

Maximum batch size: 100 Expected Machines per request.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

Array of Expected Machine update requests

Array ([ 1 .. 100 ] items)

id	string or null <uuid> ID of the Expected Machine to update. Optional for individual Expected Machine update (ignored if provided, ID from URL path is used). Required for batch update operations.
bmcMacAddress	string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 20 characters Username for accessing the Expected Machine's BMC
defaultBmcPassword	string or null <= 50 characters Password for accessing the Expected Machine's BMC
chassisSerialNumber	string or null [ 1 .. 100 ] characters Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings or null Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU to associate with this Expected Machine
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Expected Machine
siteId	string <uuid> ID of the site the Expected Machine belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Machine's BMC (Baseboard Management Controller)
chassisSerialNumber	string Serial number of the Expected Machine's chassis
fallbackDPUSerialNumbers	Array of strings Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
skuId	string or null Optional ID of the SKU associated with this Expected Machine
	object (Sku) SKU information for this Expected Machine (populated when includeRelation=Sku is specified)
machineId	string or null Optional ID of the Machine associated with this Expected Machine
	object (MachineSummary) Machine information for this Expected Machine (populated when includeRelation=Machine is specified)
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Machines
created	string <date-time> ISO 8601 datetime when the Expected Machine was created
updated	string <date-time> ISO 8601 datetime when the Expected Machine was last updated

Request samples

Payload

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"defaultBmcUsername": "newadmin",
"defaultBmcPassword": "newpassword123",
"chassisSerialNumber": "CHASSIS-54321",
"labels": {"environment": "staging",
"rack": "B2"
}
},
{"id": "597f6eca-6276-4993-bfeb-53cbbbba6f09",
"defaultBmcUsername": "newadmin2",
"defaultBmcPassword": "newpassword456",
"chassisSerialNumber": "CHASSIS-54322",
"labels": {"environment": "staging",
"rack": "B3"
}
}
]

Response samples

200
400
403
404

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"chassisSerialNumber": "CHASSIS-12345",
"fallbackDPUSerialNumbers": ["DPU-001",
"DPU-002"
],
"skuId": "lenovo.sr650v2.cpu.1",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"rackId": "rack-01",
"manufacturer": "Lenovo",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Expected Power Shelf

Expected Power Shelf identifies a Power Shelf that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Power Shelves using BMC credentials and serial numbers to help with Power Shelf discovery and ingestion.

Create Expected Power Shelf

Create an Expected Power Shelf to pre-register power shelves expected to be discovered at a Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

Expected Power Shelf creation request

siteId required	string <uuid> ID of the site the Expected Power Shelf belongs to
bmcMacAddress required	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 16 characters Username for accessing the Expected Power Shelf's BMC
defaultBmcPassword	string or null <= 20 characters Password for accessing the Expected Power Shelf's BMC
shelfSerialNumber required	string [ 1 .. 32 ] characters Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Power Shelf
siteId	string <uuid> ID of the site the Expected Power Shelf belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
shelfSerialNumber	string Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves
created	string <date-time> ISO 8601 datetime when the Expected Power Shelf was created
updated	string <date-time> ISO 8601 datetime when the Expected Power Shelf was last updated

Request samples

Payload

Content type

application/json

{"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"defaultBmcUsername": "admin",
"defaultBmcPassword": "password123",
"shelfSerialNumber": "SHELF-12345",
"ipAddress": "192.168.1.100",
"labels": {"environment": "production",
"rack": "A1"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"shelfSerialNumber": "SHELF-12345",
"ipAddress": "192.168.1.100",
"rackId": "rack-01",
"manufacturer": "Delta",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve all Expected Power Shelves

Retrieve all Expected Power Shelves.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Power Shelves if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> ID of the Site to filter Expected Power Shelves by
includeRelation	string Value: "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SHELF_SERIAL_NUMBER_ASC" "SHELF_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Expected Power Shelf
siteId	string <uuid> ID of the site the Expected Power Shelf belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
shelfSerialNumber	string Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves
created	string <date-time> ISO 8601 datetime when the Expected Power Shelf was created
updated	string <date-time> ISO 8601 datetime when the Expected Power Shelf was last updated

Response samples

200
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"shelfSerialNumber": "SHELF-12345",
"ipAddress": "192.168.1.100",
"rackId": "rack-01",
"manufacturer": "Delta",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve Expected Power Shelf

Retrieve a specific Expected Power Shelf by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedPowerShelfId required	string ID of the Expected Power Shelf

query Parameters

includeRelation

string

Value: "Site"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Power Shelf
siteId	string <uuid> ID of the site the Expected Power Shelf belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
shelfSerialNumber	string Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves
created	string <date-time> ISO 8601 datetime when the Expected Power Shelf was created
updated	string <date-time> ISO 8601 datetime when the Expected Power Shelf was last updated

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"shelfSerialNumber": "SHELF-12345",
"ipAddress": "192.168.1.100",
"rackId": "rack-01",
"manufacturer": "Delta",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Update Expected Power Shelf

Update an existing Expected Power Shelf by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Power Shelf.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedPowerShelfId required	string ID of the Expected Power Shelf

Request Body schema: application/json
required

Expected Power Shelf update request

id	string or null <uuid> ID of the Expected Power Shelf to update (ignored for single update, used for identification in batch operations).
bmcMacAddress	string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 16 characters Username for accessing the Expected Power Shelf's BMC
defaultBmcPassword	string or null <= 20 characters Password for accessing the Expected Power Shelf's BMC
shelfSerialNumber	string or null [ 1 .. 32 ] characters Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Power Shelf
siteId	string <uuid> ID of the site the Expected Power Shelf belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)
shelfSerialNumber	string Serial number of the Expected Power Shelf
ipAddress	string or null IP address of the Expected Power Shelf
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Power Shelves
created	string <date-time> ISO 8601 datetime when the Expected Power Shelf was created
updated	string <date-time> ISO 8601 datetime when the Expected Power Shelf was last updated

Request samples

Payload

Content type

application/json

{"defaultBmcUsername": "newadmin",
"defaultBmcPassword": "newpassword123",
"shelfSerialNumber": "SHELF-54321",
"ipAddress": "192.168.1.200",
"labels": {"environment": "staging",
"rack": "B2"
}
}

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"shelfSerialNumber": "SHELF-12345",
"ipAddress": "192.168.1.100",
"rackId": "rack-01",
"manufacturer": "Delta",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Expected Power Shelf

Delete an existing Expected Power Shelf by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Power Shelf.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedPowerShelfId required	string ID of the Expected Power Shelf

Responses

Response samples

400
403
404

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

Expected Switch

Expected Switch identifies a Switch that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Switches using BMC, NvOS credentials and serial numbers to help with Switch discovery and ingestion.

Create Expected Switch

Create an Expected Switch to pre-register network switches expected to be discovered at a Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Switches if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

Expected Switch creation request

siteId required	string <uuid> ID of the site the Expected Switch belongs to
bmcMacAddress required	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 16 characters Username for accessing the Expected Switch's BMC
defaultBmcPassword	string or null <= 20 characters Password for accessing the Expected Switch's BMC
switchSerialNumber required	string [ 1 .. 32 ] characters Serial number of the Expected Switch
nvOsUsername	string or null NvOS username for the Expected Switch
nvOsPassword	string or null NvOS password for the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Switch
siteId	string <uuid> ID of the site the Expected Switch belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
switchSerialNumber	string Serial number of the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches
created	string <date-time> ISO 8601 datetime when the Expected Switch was created
updated	string <date-time> ISO 8601 datetime when the Expected Switch was last updated

Request samples

Payload

Content type

application/json

{"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"defaultBmcUsername": "admin",
"defaultBmcPassword": "password123",
"switchSerialNumber": "SWITCH-12345",
"nvOsUsername": "nvadmin",
"nvOsPassword": "nvpassword123",
"labels": {"environment": "production",
"rack": "A1"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"switchSerialNumber": "SWITCH-12345",
"rackId": "rack-01",
"manufacturer": "NVIDIA",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve all Expected Switches

Retrieve all Expected Switches.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Switches if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> ID of the Site to filter Expected Switches by
includeRelation	string Value: "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SWITCH_SERIAL_NUMBER_ASC" "SWITCH_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Expected Switch
siteId	string <uuid> ID of the site the Expected Switch belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
switchSerialNumber	string Serial number of the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches
created	string <date-time> ISO 8601 datetime when the Expected Switch was created
updated	string <date-time> ISO 8601 datetime when the Expected Switch was last updated

Response samples

200
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"switchSerialNumber": "SWITCH-12345",
"rackId": "rack-01",
"manufacturer": "NVIDIA",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve Expected Switch

Retrieve a specific Expected Switch by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Switches if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedSwitchId required	string ID of the Expected Switch

query Parameters

includeRelation

string

Value: "Site"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Switch
siteId	string <uuid> ID of the site the Expected Switch belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
switchSerialNumber	string Serial number of the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches
created	string <date-time> ISO 8601 datetime when the Expected Switch was created
updated	string <date-time> ISO 8601 datetime when the Expected Switch was last updated

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"switchSerialNumber": "SWITCH-12345",
"rackId": "rack-01",
"manufacturer": "NVIDIA",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Update Expected Switch

Update an existing Expected Switch by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Switch.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Switches if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedSwitchId required	string ID of the Expected Switch

Request Body schema: application/json
required

Expected Switch update request

id	string or null <uuid> ID of the Expected Switch to update (ignored for single update, used for identification in batch operations).
bmcMacAddress	string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
defaultBmcUsername	string or null <= 16 characters Username for accessing the Expected Switch's BMC
defaultBmcPassword	string or null <= 20 characters Password for accessing the Expected Switch's BMC
switchSerialNumber	string or null [ 1 .. 32 ] characters Serial number of the Expected Switch
nvOsUsername	string or null NvOS username for the Expected Switch
nvOsPassword	string or null NvOS password for the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Expected Switch
siteId	string <uuid> ID of the site the Expected Switch belongs to
bmcMacAddress	string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ MAC address of the Expected Switch's BMC (Baseboard Management Controller)
switchSerialNumber	string Serial number of the Expected Switch
rackId	string or null Optional rack identifier for this component
name	string or null Display name for this component
manufacturer	string or null Manufacturer of this component
model	string or null Model of this component
description	string or null Description of this component
firmwareVersion	string or null Firmware version of this component
slotId	integer or null <int32> Slot ID within the rack
trayIdx	integer or null <int32> Tray index within the rack
hostId	integer or null <int32> Host ID within the tray
	object (Labels) <= 10 properties User-defined key-value pairs for organizing and categorizing Expected Switches
created	string <date-time> ISO 8601 datetime when the Expected Switch was created
updated	string <date-time> ISO 8601 datetime when the Expected Switch was last updated

Request samples

Payload

Content type

application/json

{"defaultBmcUsername": "newadmin",
"defaultBmcPassword": "newpassword123",
"switchSerialNumber": "SWITCH-54321",
"nvOsUsername": "newnvadmin",
"nvOsPassword": "newnvpassword123",
"labels": {"environment": "staging",
"rack": "B2"
}
}

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
"bmcMacAddress": "00:1A:2B:3C:4D:5E",
"switchSerialNumber": "SWITCH-12345",
"rackId": "rack-01",
"manufacturer": "NVIDIA",
"labels": {"environment": "production",
"rack": "A1"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Expected Switch

Delete an existing Expected Switch by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

Infrastructure Provider must own the Expected Switch.

Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Switches if they have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
expectedSwitchId required	string ID of the Expected Switch

Responses

Response samples

400
403
404

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

SKU

SKU (Stock Keeping Unit) defines one or more hardware configurations or Machine Bill of Materials (BOM).

SKUs are automatically derived from machine hardware characteristics and used to group similar machines. SKUs are read-only and managed by the system.

Retrieve all SKUs

Retrieve all SKUs (Stock Keeping Units) for the Infrastructure Provider or privileged Tenant.

SKUs represent unique hardware configurations discovered at sites. They are automatically derived from machine characteristics.

A siteId query parameter is required for all requests.

For Infrastructure Providers: Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

For Tenants: Org must have a Tenant with TargetedInstanceCreation capability enabled. User must have FORGE_TENANT_ADMIN role. The Tenant must have an account with the Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string <uuid> ID of the Site to retrieve SKUs from
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ID_ASC" "ID_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string Unique identifier for the SKU
siteId	string <uuid> ID of the Site this SKU belongs to
deviceType	string or null Optional device type identifier (e.g. "gpu", "cpu", "storage")
associatedMachineIds	Array of strings List of machine IDs associated with this SKU
	object (SkuComponents) Hardware components of this SKU
created	string <date-time> ISO 8601 datetime when the SKU was created
updated	string <date-time> ISO 8601 datetime when the SKU was last updated

Response samples

200
400
403

Content type

application/json

[{"id": "lenovo.sr650v2.cpu.1",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"deviceType": "gpu",
"associatedMachineIds": ["fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g"
],
"components": {"cpus": [{"vendor": "Intel",
"model": "Xeon Platinum 8480+",
"threadCount": 112,
"count": 2
}
],
"gpus": [{"vendor": "NVIDIA",
"model": "H100 SXM5",
"totalMemory": "80GB HBM3",
"count": 8
}
],
"memory": [{"capacityMb": 65536,
"memoryType": "DDR5",
"count": 16
}
],
"storage": [{"vendor": "Samsung",
"model": "PM9A3",
"capacityMb": 7680000,
"count": 4
}
],
"chassis": {"vendor": "Supermicro",
"model": "SYS-420GP-TNR"
}
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve SKU

Retrieve a specific SKU (Stock Keeping Unit) by ID.

SKUs represent unique hardware configurations discovered at sites. They are automatically derived from machine characteristics.

For Infrastructure Providers: Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

For Tenants: Org must have a Tenant with TargetedInstanceCreation capability enabled. User must have FORGE_TENANT_ADMIN role. The Tenant must have an account with the SKU's Site's Infrastructure Provider.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
skuId required	string ID of the SKU

Responses

Response Schema: application/json

id	string Unique identifier for the SKU
siteId	string <uuid> ID of the Site this SKU belongs to
deviceType	string or null Optional device type identifier (e.g. "gpu", "cpu", "storage")
associatedMachineIds	Array of strings List of machine IDs associated with this SKU
	object (SkuComponents) Hardware components of this SKU
created	string <date-time> ISO 8601 datetime when the SKU was created
updated	string <date-time> ISO 8601 datetime when the SKU was last updated

Response samples

200
400
403
404

Content type

application/json

{"id": "lenovo.sr650v2.cpu.1",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"deviceType": "gpu",
"associatedMachineIds": ["fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g"
],
"components": {"cpus": [{"vendor": "Intel",
"model": "Xeon Platinum 8480+",
"threadCount": 112,
"count": 2
}
],
"gpus": [{"vendor": "NVIDIA",
"model": "H100 SXM5",
"totalMemory": "80GB HBM3",
"count": 8
}
],
"memory": [{"capacityMb": 65536,
"memoryType": "DDR5",
"count": 16
}
],
"storage": [{"vendor": "Samsung",
"model": "PM9A3",
"capacityMb": 7680000,
"count": 4
}
],
"chassis": {"vendor": "Supermicro",
"model": "SYS-420GP-TNR"
}
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

InfiniBand Partition

InfiniBand (IB) is a high-performance, low-latency networking standard designed for interconnecting servers and storage in HPC (High-Performance Computing) and AI systems, utilizing RDMA (Remote Direct Memory Access) to reduce CPU overhead. InfiniBand Partitions are used to group Machines into logical partitions for network isolation and load distribution.

Retrieve all InfiniBand Partitions

Retrieve all InfiniBand Partitions for the org

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter Partitions by Site
status	string Filter Partitions by Status
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "Site" "VPC" "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
controllerIBPartitionId	string or null <uuid>
partitionKey	string or null
partitionName	string or null
serviceLevel	integer or null [ 0 .. 15 ]
rateLimit	number or null Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
mtu	integer or null Enum: 4000 8000
enableSharp	boolean
	object (Labels) <= 10 properties String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified
status	string (InfiniBandPartitionStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status values for InfiniBand Partition objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "turbo-net",
"description": "InfiniBand Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
"partitionKey": "0x1",
"partitionName": "turbo-net",
"serviceLevel": 5,
"rateLimit": 40,
"mtu": 4000,
"enableSharp": true,
"labels": {"environment": "production",
"team": "devops"
},
"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"
}
]

Create InfiniBand Partition

Create an InfiniBand Partition for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Name of the Partition to create
description	string Optional description of the Partition
siteId required	string <uuid> ID of the Site the Partition should belong to
	object (Labels) <= 10 properties String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
controllerIBPartitionId	string or null <uuid>
partitionKey	string or null
partitionName	string or null
serviceLevel	integer or null [ 0 .. 15 ]
rateLimit	number or null Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
mtu	integer or null Enum: 4000 8000
enableSharp	boolean
	object (Labels) <= 10 properties String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified
status	string (InfiniBandPartitionStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status values for InfiniBand Partition objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "turbo-net",
"siteId": "69dae3c8-3554-4a1f-b391-858c6dc47fff",
"labels": {"environment": "production",
"team": "devops"
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "turbo-net",
"description": "InfiniBand Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
"partitionKey": "0x1",
"partitionName": "turbo-net",
"serviceLevel": 5,
"rateLimit": 40,
"mtu": 4000,
"enableSharp": true,
"labels": {"environment": "production",
"team": "devops"
},
"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"
}

Retrieve InfiniBand Partition

Retrieve a specific InfiniBand Partition

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Tenant must own the Partition.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
infiniBandPartitionId required	string ID of the InfiniBand Partition

query Parameters

includeRelation

string

Enum: "Site" "VPC" "Tenant"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
controllerIBPartitionId	string or null <uuid>
partitionKey	string or null
partitionName	string or null
serviceLevel	integer or null [ 0 .. 15 ]
rateLimit	number or null Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
mtu	integer or null Enum: 4000 8000
enableSharp	boolean
	object (Labels) <= 10 properties String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified
status	string (InfiniBandPartitionStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status values for InfiniBand Partition objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "turbo-net",
"description": "InfiniBand Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
"partitionKey": "0x1",
"partitionName": "turbo-net",
"serviceLevel": 5,
"rateLimit": 40,
"mtu": 4000,
"enableSharp": true,
"labels": {"environment": "production",
"team": "devops"
},
"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"
}

Delete InfiniBand Partition

Delete a specific InfiniBand Partition by ID.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Tenant must own the Partition.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
infiniBandPartitionId required	string ID of the InfiniBand Partition

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update InfiniBand Partition

Update an existing InfiniBand Partition

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Tenant must own the Partition.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
infiniBandPartitionId required	string ID of the InfiniBand Partition

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string
	object (Labels) <= 10 properties String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
controllerIBPartitionId	string or null <uuid>
partitionKey	string or null
partitionName	string or null
serviceLevel	integer or null [ 0 .. 15 ]
rateLimit	number or null Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
mtu	integer or null Enum: 4000 8000
enableSharp	boolean
	object (Labels) <= 10 properties String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified
status	string (InfiniBandPartitionStatus) Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error" Status values for InfiniBand Partition objects
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "turbo-net-v2",
"description": "Second version of the model training network",
"labels": {"environment": "production",
"team": "devops"
}
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "turbo-net-v2",
"description": "Second version of the model training network",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
"partitionKey": "0x1",
"partitionName": "turbo-net",
"serviceLevel": 5,
"rateLimit": 40,
"mtu": 4000,
"enableSharp": true,
"labels": {"environment": "production",
"team": "devops"
},
"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"
}

Retrieve all InfiniBand Interfaces

Get all InfiniBand Interfaces

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string Filter InfiniBand Interfaces by Site ID. Can be specified multiple times to filter on more than one ID.
instanceId	string Filter InfiniBand Interfaces by Instance ID. Can be specified multiple times to filter on more than one ID.
infinibandPartitionId	string Filter InfiniBand Interfaces by InfiniBand Partition ID. Can be specified multiple times to filter on more than one ID.
status	string Filter InfiniBand Interfaces by Status. Can be specified multiple times to filter on more than one status.
includeRelation	string Enum: "Instance" "InfiniBandPartition" "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> non-empty
instanceId	string <uuid>
partitionId	string <uuid> ID of the InfiniBand Partition associated with this interface
device	string Name of the InfiniBand device associated with this interface
deviceInstance	integer
isPhysical	boolean Indicates whether this is a physical interface
virtualFunctionId	integer or null
guid	string or null
status	string (InfiniBandInterfaceStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for InfiniBand Interface objects
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

NVLink Logical Partition

NVLink Logical Partitions are used to group GPUs into logical partitions for shared memory and low-latency direct communication between GPUs.

Retrieve all NVLink Logical Partitions

Retrieve all NVLink Logical Partitions for the org

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the NGC Org

query Parameters

siteId	string <uuid> Filter NVLink Logical Partitions by Site
status	string Filter NVLink Logical Partitions by Status
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeInterfaces	boolean Include NVLink Interfaces in response.
includeStats	boolean Include NVLink Logical Partition Stats in response.
includeVpcs	boolean Include VPCs in response.
includeRelation	string Enum: "Site" "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique ID of the NVLink Logical Partition
name	string [ 2 .. 256 ] characters Name of the NVLink Logical Partition
description	string Optional description of the NVLink Logical Partition
siteId	string <uuid> ID of the Site the NVLink Logical Partition belongs to
tenantId	string <uuid> ID of the Tenant the NVLink Logical Partition belongs to
status	string (NVLinkLogicalPartitionStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Deleting" "Error" Status of the NVLink Logical Partition
	Array of objects (StatusDetail) Details of status changes for the NVLink Logical Partition over time
created	string <date-time> Date and time the NVLink Logical Partition was created
updated	string <date-time> Date and time the NVLink Logical Partition was last updated

Response samples

200
403

Content type

application/json

[{"id": "ded96bdf-905e-40dd-8a58-3472aab60042",
"name": "partition-east-gpu",
"description": "NVLink Logical Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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"
}
]

Create NVLink Logical Partition

Create an NVLink Logical Partition for the org.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN NGC role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the NGC Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Name of the NVLink Logical Partition to create
description	string Optional description of the NVLink Logical Partition
siteId required	string <uuid> ID of the Site the NVLink Logical Partition should belong to

Responses

Response Schema: application/json

id	string <uuid> Unique ID of the NVLink Logical Partition
name	string [ 2 .. 256 ] characters Name of the NVLink Logical Partition
description	string Optional description of the NVLink Logical Partition
siteId	string <uuid> ID of the Site the NVLink Logical Partition belongs to
tenantId	string <uuid> ID of the Tenant the NVLink Logical Partition belongs to
status	string (NVLinkLogicalPartitionStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Deleting" "Error" Status of the NVLink Logical Partition
	Array of objects (StatusDetail) Details of status changes for the NVLink Logical Partition over time
created	string <date-time> Date and time the NVLink Logical Partition was created
updated	string <date-time> Date and time the NVLink Logical Partition was last updated

Request samples

Payload

Content type

application/json

{"name": "partition-east-gpu",
"siteId": "69dae3c8-3554-4a1f-b391-858c6dc47fff"
}

Response samples

201
400
403

Content type

application/json

{"id": "ded96bdf-905e-40dd-8a58-3472aab60042",
"name": "partition-east-gpu",
"description": "NVLink Logical Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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"
}

Retrieve NVLink Logical Partition

Retrieve a specific NVLink Logical Partition by ID

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN NGC role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the NGC Org
nvLinkLogicalPartitionId required	string ID of the NVLink Logical Partition

query Parameters

includeInterfaces	string Include all attached NVLink Interfaces in response
includeStats	boolean Include NVLink Logical Partition Stats in response
includeVpcs	boolean Include all attached VPCs in response
includeRelation	string Enum: "Site" "Tenant" Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique ID of the NVLink Logical Partition
name	string [ 2 .. 256 ] characters Name of the NVLink Logical Partition
description	string Optional description of the NVLink Logical Partition
siteId	string <uuid> ID of the Site the NVLink Logical Partition belongs to
tenantId	string <uuid> ID of the Tenant the NVLink Logical Partition belongs to
status	string (NVLinkLogicalPartitionStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Deleting" "Error" Status of the NVLink Logical Partition
	Array of objects (StatusDetail) Details of status changes for the NVLink Logical Partition over time
created	string <date-time> Date and time the NVLink Logical Partition was created
updated	string <date-time> Date and time the NVLink Logical Partition was last updated

Response samples

200
403

Content type

application/json

{"id": "ded96bdf-905e-40dd-8a58-3472aab60042",
"name": "partition-east-gpu",
"description": "Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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"
}

Update NVLink Logical Partition

Update a specific NVLink Logical Partition

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN NGC role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the NGC Org
nvLinkLogicalPartitionId required	string ID of the NVLink Logical Partition

Request Body schema: application/json

name	string [ 2 .. 256 ] characters Updated name for the NVLink Logical Partition
description	string Updated description for the NVLink Logical Partition

Responses

Response Schema: application/json

id	string <uuid> Unique ID of the NVLink Logical Partition
name	string [ 2 .. 256 ] characters Name of the NVLink Logical Partition
description	string Optional description of the NVLink Logical Partition
siteId	string <uuid> ID of the Site the NVLink Logical Partition belongs to
tenantId	string <uuid> ID of the Tenant the NVLink Logical Partition belongs to
status	string (NVLinkLogicalPartitionStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Deleting" "Error" Status of the NVLink Logical Partition
	Array of objects (StatusDetail) Details of status changes for the NVLink Logical Partition over time
created	string <date-time> Date and time the NVLink Logical Partition was created
updated	string <date-time> Date and time the NVLink Logical Partition was last updated

Request samples

Payload

Content type

application/json

{"name": "partition-east-gpu",
"description": "NVLink Logical Partition for model training Instances"
}

Response samples

200
400
403

Content type

application/json

{"id": "ded96bdf-905e-40dd-8a58-3472aab60042",
"name": "partition-east-gpu",
"description": "Partition for model training Instances",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"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"
}

Delete NVLink Logical Partition

Delete an NVLink Logical Partition by ID

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN NGC role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the NGC Org
nvLinkLogicalPartitionId required	string ID of the NVLink Logical Partition

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Retrieve all NVLink Interfaces

Get all NVLink Interfaces

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN NGC role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the NGC Org

query Parameters

status	string Filter NVLink Interfaces by Status. Can be specified multiple times to filter on more than one status.
siteId	string Filter NVLink Interfaces by Site ID. Can be specified multiple times to filter on more than one ID.
instanceId	string Filter NVLink Interfaces by Instance ID. Can be specified multiple times to filter on more than one ID.
nvLinkLogicalPartitionId	string Filter NVLink Interfaces by NVLink Logical Partition ID. Can be specified multiple times to filter on more than one ID.
nvLinkDomainId	string Filter NVLink Interfaces by NVLink Domain ID. Can be specified multiple times to filter on more than one ID.
includeRelation	string Enum: "Instance" "NVLinkLogicalPartition" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> non-empty
instanceId	string <uuid>
nvLinkLogicalPartitionId	string <uuid> ID of the NVLink Logical Partition associated with this interface
nvLinkDomainId	string <uuid> ID of the NVLink Domain associated with this Interface
deviceInstance	integer Index of the device, used to identify the GPU associated with this Interface
gpuGuid	string Unique ID of the GPU
status	string (NVLinkInterfaceStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for NVLink Interface objects
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"nvLinkLogicalPartitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"nvLinkDomainId": "4b145552-0d8f-45ff-b652-eed105f93e50",
"deviceInstance": 0,
"gpuGuid": "5108732638879268442",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Operating System

Operating Systems in NICo are typically iPXE scripts that are used to boot Machines.

Retrieve all Operating Systems

Get an Operating System by ID

If the Operating System has infrastructureProviderId set, then org must have an Infrastructure Provider entity and its ID should match the Operating System Infrastructure Provider ID. User must have FORGE_PROVIDER_ADMIN authorization role.

If the Operating System has tenantId set, then org must have a Tenant entity and its ID should match the Operating System Tenant ID. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string Filter Operating Systems by Site ID. Can be specified multiple times to filter on more than one ID.
type	string Enum: "Image" "iPXE" Filter Operating Systems by Type
status	string Filter Operating Systems by Status. Can be specified multiple times to filter on more than one status.
query	string Provide query to search for matches. Input will be matched against name, description and status fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> ID of the Operating System
name	string [ 2 .. 256 ] characters Name of the Operating System
description	string Optional description of the Operating System
infrastructureProviderId	string or null <uuid> Specified if a Provider owns the Operating System
tenantId	string or null <uuid> Specified if a Tenant owns the Operating System
type	string Enum: "iPXE" "Image" Type of the Operating System
imageUrl	string or null <uri> Original URL from where the Operating System image can be retrieved
imageSha	string or null SHA hash of the image file, only present for image based OS
imageAuthType	string or null Authentication type for image URL e.g. 'Basic' or 'Bearer'
imageAuthToken	string or null Auth token to retrieve the image from image URL
imageDisk	string or null Disk path where the image should be monuted
rootFsId	string or null Root filesystem UUID, only applicable for image based Operating System
rootFsLabel	string or null Root filesystem label, only applicable for image based Operating System
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean Specified when the Operating System is Cloud Init based
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 or null Optional deactivation note if OS is inactive
allowOverride	boolean Indicates if the user data can be overridden at Instance creation time
	Array of objects (OperatingSystemSiteAssociation) Sites the Operating System is synced to
status	string (OperatingSystemStatus) Enum: "Pending" "Provisioning" "Syncing" "Ready" "Deleting" "Error" "Deactivated" Status of the Operating System
	Array of objects (StatusDetail) History of status changes over time
created	string <date-time> Date/time when the Operating System was created
updated	string <date-time> Date/time when the Operating System was updated

Response samples

200
403

Content type

application/json

Example

example-1

[{"id": "42b0f982-5c61-4d2f-a018-41ece61f4641",
"name": "debian-12-amd64",
"description": "Official Debian 12 for AMD/Intel",
"infrastructureProviderId": null,
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"type": "Image",
"imageUrl": "https://saimei.ftp.acc.umu.se/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2",
"imageSha": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
"imageAuthType": "Bearer",
"imageAuthToken": "acbd18db4cc2f85cedef654fccc4a4d8",
"imageDisk": "/dev/sda",
"rootFsId": "6c2ac315-3040-4728-94eb-b66d320206c1",
"ipxeScript": null,
"userData": null,
"isCloudInit": true,
"phoneHomeEnabled": false,
"allowOverride": false,
"siteAssociations": [{"site": {"id": "4b36152c-f48d-4bcc-a722-0fd8e2ad209a",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": false,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"site": {"id": "219b7913-4494-4589-940e-e78ca879b302",
"name": "sc-west-4",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": false,
"networkSecurityGroup": false,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"isActive": true,
"deactivationNote": null,
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "received Operating System creation request, syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create 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 param value. User must have FORGE_PROVIDER_ADMIN role.

If tenantId is provided in request data, then org must have a Tenant entity and its ID should match the query param value. User must have FORGE_TENANT_ADMIN role.

Only Tenants are allowed to create Operating System for MVP.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Name of the Operating System
description	string Optional description of the Operating System
infrastructureProviderId	string or null <uuid> Deprecated Deprecated: Infrastructure Provider is now inferred from org membership.
tenantId	string or null <uuid> Deprecated Deprecated: Tenant is now inferred from org membership.
siteIds	Array of strings <uuid> [ items <uuid > ] Specified only one Site if an Operating System is Image based, more than one Site is not supported"
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based OS. Cannot be specified if imageUrl is specified
imageUrl	string or null <uri> Original URL from where the Operating System image can be retreived from, required for image based OS. Cannot be specified if ipxeScript is specified
imageSha	string or null SHA hash of the image file, required for image based OS
imageAuthType	string or null Authentication type for image URL if needed e.g. basic/bearer/token, required is imageAuthToken is specified
imageAuthToken	string or null Auth token to retrieve the image from image URL, required if imageAuthType is specified
imageDisk	string or null Disk path where the image should be mounted, optional
rootFsId	string or null Root filesystem UUID, this or `rootFsLabel` required for image based OS
rootFsLabel	string or null Root filesystem label, this or `rootFsId` required for image based OS
phoneHomeEnabled	boolean or null Indicates whether the Phone Home service should be enabled or disabled for Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean Specified when the Operating System is Cloud Init based
allowOverride	boolean Indicates if the user data can be overridden at Instance creation time

Responses

Response Schema: application/json

id	string <uuid> ID of the Operating System
name	string [ 2 .. 256 ] characters Name of the Operating System
description	string Optional description of the Operating System
infrastructureProviderId	string or null <uuid> Specified if a Provider owns the Operating System
tenantId	string or null <uuid> Specified if a Tenant owns the Operating System
type	string Enum: "iPXE" "Image" Type of the Operating System
imageUrl	string or null <uri> Original URL from where the Operating System image can be retrieved
imageSha	string or null SHA hash of the image file, only present for image based OS
imageAuthType	string or null Authentication type for image URL e.g. 'Basic' or 'Bearer'
imageAuthToken	string or null Auth token to retrieve the image from image URL
imageDisk	string or null Disk path where the image should be monuted
rootFsId	string or null Root filesystem UUID, only applicable for image based Operating System
rootFsLabel	string or null Root filesystem label, only applicable for image based Operating System
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean Specified when the Operating System is Cloud Init based
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 or null Optional deactivation note if OS is inactive
allowOverride	boolean Indicates if the user data can be overridden at Instance creation time
	Array of objects (OperatingSystemSiteAssociation) Sites the Operating System is synced to
status	string (OperatingSystemStatus) Enum: "Pending" "Provisioning" "Syncing" "Ready" "Deleting" "Error" "Deactivated" Status of the Operating System
	Array of objects (StatusDetail) History of status changes over time
created	string <date-time> Date/time when the Operating System was created
updated	string <date-time> Date/time when the Operating System was updated

Request samples

Payload

Content type

application/json

Example

example-1

{"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",
"isCloudInit": true,
"phoneHomeEnabled": true,
"allowOverride": false
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "ubuntu-22.04",
"description": "Ubuntu 22.04",
"infrastructureProviderId": null,
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"type": "iPXE",
"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",
"isCloudInit": true,
"phoneHomeEnabled": false,
"allowOverride": false,
"imageAuthToken": null,
"imageAuthType": null,
"imageDisk": null,
"imageSha": null,
"imageUrl": null,
"rootFsId": null,
"rootFsLabel": null,
"siteAssociations": [ ],
"isActive": true,
"deactivationNote": null,
"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"
}

Retrieve Operating System

Get an Operating System by ID

If the Operating System has infrastructureProviderId set, then org must have an Infrastructure Provider entity and its ID should match the Operating System Infrastructure Provider ID. User must have FORGE_PROVIDER_ADMIN authorization role.

If the Operating System has tenantId set, then org must have a Tenant entity and its ID should match the Operating System Tenant ID. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
operatingSystemId required	string ID of the Operating System

query Parameters

includeRelation

string

Enum: "InfrastructureProvider" "Tenant"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> ID of the Operating System
name	string [ 2 .. 256 ] characters Name of the Operating System
description	string Optional description of the Operating System
infrastructureProviderId	string or null <uuid> Specified if a Provider owns the Operating System
tenantId	string or null <uuid> Specified if a Tenant owns the Operating System
type	string Enum: "iPXE" "Image" Type of the Operating System
imageUrl	string or null <uri> Original URL from where the Operating System image can be retrieved
imageSha	string or null SHA hash of the image file, only present for image based OS
imageAuthType	string or null Authentication type for image URL e.g. 'Basic' or 'Bearer'
imageAuthToken	string or null Auth token to retrieve the image from image URL
imageDisk	string or null Disk path where the image should be monuted
rootFsId	string or null Root filesystem UUID, only applicable for image based Operating System
rootFsLabel	string or null Root filesystem label, only applicable for image based Operating System
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean Specified when the Operating System is Cloud Init based
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 or null Optional deactivation note if OS is inactive
allowOverride	boolean Indicates if the user data can be overridden at Instance creation time
	Array of objects (OperatingSystemSiteAssociation) Sites the Operating System is synced to
status	string (OperatingSystemStatus) Enum: "Pending" "Provisioning" "Syncing" "Ready" "Deleting" "Error" "Deactivated" Status of the Operating System
	Array of objects (StatusDetail) History of status changes over time
created	string <date-time> Date/time when the Operating System was created
updated	string <date-time> Date/time when the Operating System was updated

Response samples

200
403

Content type

application/json

Example

Image Based OS

{"id": "42b0f982-5c61-4d2f-a018-41ece61f4641",
"name": "debian-12-amd64",
"description": "Official Debian 12 for AMD/Intel",
"infrastructureProviderId": null,
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"type": "Image",
"imageUrl": "https://saimei.ftp.acc.umu.se/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2",
"imageSha": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
"imageAuthType": "Bearer",
"imageAuthToken": "acbd18db4cc2f85cedef654fccc4a4d8",
"imageDisk": "/dev/sda",
"rootFsId": "6c2ac315-3040-4728-94eb-b66d320206c1",
"rootFsLabel": null,
"ipxeScript": null,
"userData": null,
"isCloudInit": true,
"phoneHomeEnabled": false,
"allowOverride": false,
"siteAssociations": [{"site": {"id": "4b36152c-f48d-4bcc-a722-0fd8e2ad209a",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": false,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"site": {"id": "219b7913-4494-4589-940e-e78ca879b302",
"name": "sc-west-4",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": false,
"networkSecurityGroup": false,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"isActive": true,
"deactivationNote": null,
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "received Operating System creation request, syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Operating System

Delete an Operating System by ID

If the Operating System has infrastructureProviderId set, then org must have an Infrastructure Provider entity and its ID should match the Operating System Infrastructure Provider ID. User must have FORGE_PROVIDER_ADMIN authorization role.

If the Operating System has tenantId set, then org must have a Tenant entity and its ID should match the Operating System Tenant ID. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
operatingSystemId required	string ID of the Operating System

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update Operating System

Update an Operating System by ID

If the Operating System has infrastructureProviderId set, then org must have an Infrastructure Provider entity and its ID should match the Operating System Infrastructure Provider ID. User must have FORGE_PROVIDER_ADMIN authorization role. Provider must own the Operating System.

If the Operating System has tenantId set, then org must have a Tenant entity and its ID should match the Operating System Tenant ID. User must have FORGE_TENANT_ADMIN role. Tenant must own the Operating System.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
operatingSystemId required	string ID of the Operating System

Request Body schema: application/json

name	string or null [ 2 .. 256 ] characters Name of the Operating System
description	string or null Optional description of the Operating System
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based OS. Cannot be specified if imageUrl is specified
imageUrl	string or null <uri> Original URL from where the Operating System image can be retreived from, required for image based OS
imageSha	string or null SHA hash of the image file, required for image based OS
imageAuthType	string or null Authentication type for image URL if needed e.g. basic/bearer/token, required is imageAuthToken is specified
imageAuthToken	string or null Auth token to retrieve the image from image URL, required if imageAuthType is specified
imageDisk	string or null Disk path where the image should be mounted, optional
rootFsId	string or null Root filesystem UUID, this or `rootFsLabel` required for image based OS
rootFsLabel	string or null Root filesystem label, this or `rootFsId` required for image based OS
phoneHomeEnabled	boolean or null Indicates whether the Phone Home service should be enabled or disabled for Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean or null Specified when the Operating System is Cloud Init based
allowOverride	boolean or null Indicates if the user data can be overridden at Instance creation time
isActive	boolean or null Indicates if the Operating System is active
deactivationNote	string or null Optional deactivation note if OS is inactive

Responses

Response Schema: application/json

id	string <uuid> ID of the Operating System
name	string [ 2 .. 256 ] characters Name of the Operating System
description	string Optional description of the Operating System
infrastructureProviderId	string or null <uuid> Specified if a Provider owns the Operating System
tenantId	string or null <uuid> Specified if a Tenant owns the Operating System
type	string Enum: "iPXE" "Image" Type of the Operating System
imageUrl	string or null <uri> Original URL from where the Operating System image can be retrieved
imageSha	string or null SHA hash of the image file, only present for image based OS
imageAuthType	string or null Authentication type for image URL e.g. 'Basic' or 'Bearer'
imageAuthToken	string or null Auth token to retrieve the image from image URL
imageDisk	string or null Disk path where the image should be monuted
rootFsId	string or null Root filesystem UUID, only applicable for image based Operating System
rootFsLabel	string or null Root filesystem label, only applicable for image based Operating System
ipxeScript	string or null iPXE script or URL, only applicable for iPXE based Operating System
userData	string or null User data for the Operating System
isCloudInit	boolean Specified when the Operating System is Cloud Init based
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 or null Optional deactivation note if OS is inactive
allowOverride	boolean Indicates if the user data can be overridden at Instance creation time
	Array of objects (OperatingSystemSiteAssociation) Sites the Operating System is synced to
status	string (OperatingSystemStatus) Enum: "Pending" "Provisioning" "Syncing" "Ready" "Deleting" "Error" "Deactivated" Status of the Operating System
	Array of objects (StatusDetail) History of status changes over time
created	string <date-time> Date/time when the Operating System was created
updated	string <date-time> Date/time when the Operating System was updated

Request samples

Payload

Content type

application/json

{"name": "ubuntu-22.04-lts",
"description": "Ubuntu 22.04 LTS",
"allowOverride": true
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "ubuntu-22.04-lts",
"description": "Ubuntu 22.04 LTS",
"infrastructureProviderId": null,
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"type": "iPXE",
"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",
"isCloudInit": true,
"allowOverride": true,
"phoneHomeEnabled": true,
"imageAuthToken": null,
"imageAuthType": null,
"imageDisk": null,
"imageSha": null,
"imageUrl": null,
"rootFsId": null,
"rootFsLabel": null,
"siteAssociations": [ ],
"isActive": true,
"deactivationNote": null,
"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"
}

Instance Type

Instance Types allow grouping Machines into a pool defined by their capabilities. Providers can then allocate a portion of the Instance Type pool to a Tenant.

Deprecation history:

includeMachineAssociation was deprecated in favor of includeMachineAssignment and was removed on July 26th, 2023 0:00 UTC. Please use includeMachineAssignment instead.
displayName attribute was deprecated and removed on October 30, 2024 0:00 UTC. Please update your usage accordingly.

Retrieve all Instance Types

Get all Instance Types for the org.

Provider and Tenant roles are inferred from the org's membership. User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Results are returned from both Provider and Tenant perspectives when the org has both roles.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter Instance Types by Site ID
infrastructureProviderId	string <uuid> Deprecated Filter Instance Types by Infrastructure Provider ID.
tenantId	string <uuid> Deprecated Filter Instance Types by Tenant ID.
status	string Filter Instance Types by Status
query	string Search for matches across all Sites. Input will be matched against name, display name, description, labels and status fields
includeRelation	string Enum: "InfrastructureProvider" "Site" Related entity to expand
includeMachineAssignment	boolean Include Machine assignments for each Instance Type. Can only be requested by Provider.
includeAllocationStats	boolean Include Allocation stats.
excludeUnallocated	boolean Excludes InstanceType records that have no allocations from being returned in the result set. Currently can only be requested by Tenant.
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
controllerMachineType	string
infrastructureProviderId	string <uuid>
siteId	string <uuid>
	object (Labels) <= 10 properties
	Array of objects (MachineCapability)
	Array of objects (MachineInstanceType) Available only for Providers
	object (InstanceTypeAllocationStats) summary of machine counts by allocation status
status	string (InstanceTypeStatus) Enum: "Pending" "Registering" "Ready" "Deleting" "Error" Status values for Instance Type objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

Example

example-1

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "x3.large",
"description": "Part of X family, the X3 Large features increased compute power",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
}
],
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"queryParam": "includeMachineAssociation",
"replacedBy": "includeMachineAssignment",
"takeActionBy": "2023-07-26T00:00:00Z",
"notice": "'includeMachineAssociation' has been deprecated in favor of 'includeMachineAssignment'. Please take action immediately."
},
{"attribute": "displayName",
"takeActionBy": "2024-10-30T00:00:00Z",
"notice": "'displayName' has been deprecated. Please take action immediately."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create an Instance Type

Create an Instance Type for Infrastructure Provider.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string
siteId required	string <uuid>
	object (Labels) <= 10 properties
controllerMachineType	string
	Array of objects (InstanceTypeCapabilityCreateRequest)

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
controllerMachineType	string
infrastructureProviderId	string <uuid>
siteId	string <uuid>
	object (Labels) <= 10 properties
	Array of objects (MachineCapability)
	Array of objects (MachineInstanceType) Available only for Providers
	object (InstanceTypeAllocationStats) summary of machine counts by allocation status
status	string (InstanceTypeStatus) Enum: "Pending" "Registering" "Ready" "Deleting" "Error" Status values for Instance Type objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

Example

example-1

{"name": "x3.large",
"description": "Part of X family, the X3 Large features increased compute power",
"siteId": "8d97fa69-9199-49ff-bcf3-168c62d3874e",
"labels": {"region": "portland",
"env": "staging"
},
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"count": 2
},
{"type": "Memory",
"name": "Corsair Vengeance LPX",
"capacity": "32GB",
"count": 4
}
]
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "x3.large",
"description": "Part of X family, the X3 Large features increased compute power",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"labels": {"region": "portland",
"env": "staging"
},
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{"type": "Memory",
"name": "Corsair Vengeance LPX",
"capacity": "32GB",
"count": 4
}
],
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"queryParam": "includeMachineAssociation",
"replacedBy": "includeMachineAssignment",
"takeActionBy": "2023-07-26T00:00:00Z",
"notice": "'includeMachineAssociation' has been deprecated in favor of 'includeMachineAssignment'. Please take action immediately."
},
{"attribute": "displayName",
"takeActionBy": "2024-10-30T00:00:00Z",
"notice": "'displayName' has been deprecated. Please take action immediately."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve an Instance Type

Get an Instance Type by ID.

If the org has an Infrastructure Provider entity that owns the Instance Type, then the Instance Type detail is returned. User must have FORGE_PROVIDER_ADMIN role.

If the org has a Tenant entity and it has a Tenant Account with the Infrastructure Provider of the Instance Type, then the Instance Type detail is returned. User must have FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type

query Parameters

includeMachineAssociation	boolean Include Machine associations for each Instance Type. Can only be requested by Provider
includeAllocationStats	boolean Include Allocation stats. Currently can only be requested by Tenant
includeRelation	string Enum: "InfrastructureProvider" "Site" Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
controllerMachineType	string
infrastructureProviderId	string <uuid>
siteId	string <uuid>
	object (Labels) <= 10 properties
	Array of objects (MachineCapability)
	Array of objects (MachineInstanceType) Available only for Providers
	object (InstanceTypeAllocationStats) summary of machine counts by allocation status
status	string (InstanceTypeStatus) Enum: "Pending" "Registering" "Ready" "Deleting" "Error" Status values for Instance Type objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "x3.large",
"description": "Part of X family, the X3 Large features increased compute power",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"labels": {"region": "portland",
"env": "staging"
},
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
}
],
"allocationStats": {"assigned": 30,
"total": 10,
"used": 3,
"unused": 7,
"unusedUsable": 7,
"maxAllocatable": 20
},
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"queryParam": "includeMachineAssociation",
"replacedBy": "includeMachineAssignment",
"takeActionBy": "2023-07-26T00:00:00Z",
"notice": "'includeMachineAssociation' has been deprecated in favor of 'includeMachineAssignment'. Please take action immediately."
},
{"attribute": "displayName",
"takeActionBy": "2024-10-30T00:00:00Z",
"notice": "'displayName' has been deprecated. Please take action immediately."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Instance Type

Delete an Instance Type by ID.

Org must have an Infrastructure Provider entity that owns the Instance Type. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update Instance Type

Update an Instance Type by ID.

Org must have an Infrastructure Provider entity that owns the Instance Type. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type

Request Body schema: application/json

name	string [ 2 .. 256 ] characters
description	string
	object (Labels) <= 10 properties
	Array of objects (MachineCapability)

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
controllerMachineType	string
infrastructureProviderId	string <uuid>
siteId	string <uuid>
	object (Labels) <= 10 properties
	Array of objects (MachineCapability)
	Array of objects (MachineInstanceType) Available only for Providers
	object (InstanceTypeAllocationStats) summary of machine counts by allocation status
status	string (InstanceTypeStatus) Enum: "Pending" "Registering" "Ready" "Deleting" "Error" Status values for Instance Type objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"description": "Updated version of the X3 Large family of machines",
"labels": {"region": "portland",
"env": "staging"
},
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
}
]
}

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "x3.large",
"description": "Updated version of the X3 Large family of machines",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
"labels": {"region": "portland",
"env": "staging"
},
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
}
],
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"queryParam": "includeMachineAssociation",
"replacedBy": "includeMachineAssignment",
"takeActionBy": "2023-07-26T00:00:00Z",
"notice": "'includeMachineAssociation' has been deprecated in favor of 'includeMachineAssignment'. Please take action immediately."
},
{"attribute": "displayName",
"takeActionBy": "2024-10-30T00:00:00Z",
"notice": "'displayName' has been deprecated. Please take action immediately."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve all Machines/Instance Type associations

Get all Machines for a given Instance Type

Org must have an Infrastructure Provider entity that owns the Instance Type and the Machine. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type

query Parameters

pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Deprecated Deprecated: Use `machineId` when identifying a Machine/Instance Type association. This field will be removed on July 9th, 2026 0:00 UTC.
machineId	string
instanceTypeId	string <uuid>
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "f690ffcd-06b7-430c-9c2a-b9afd18d77c3",
"machineId": "fm100htrh18t1lrjg2pqagkh3sfigr9m65dejvkq168ako07sc0uibpp5q0",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create a Machine/Instance Type association

Associate a Machine to an Instance Type

Org must have an Infrastructure Provider entity that owns the Instance Type and the Machine. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type

Request Body schema: application/json

machineIds

required

Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Response Schema: application/json

Array

id	string <uuid> Deprecated Deprecated: Use `machineId` when identifying a Machine/Instance Type association. This field will be removed on July 9th, 2026 0:00 UTC.
machineId	string
instanceTypeId	string <uuid>
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"machineIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08",
"59c8d465-69f1-447f-80f8-1bc85627a03b",
"0a44ffc3-39ba-46c6-b483-be00a1e2cc27"
]
}

Response samples

201
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "f690ffcd-06b7-430c-9c2a-b9afd18d77c3",
"machineId": "fm100ht68sf2m52idrpslcjkpdj5r3tb3j5o0bkfubhoglbq47u18nknfog",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "f690ffcd-06b7-430c-9c2a-b9afd18d77c3",
"machineId": "fm100htrh18t1lrjg2pqagkh3sfigr9m65dejvkq168ako07sc0uibpp5q0",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Delete a Machine/Instance Type association

Delete a Machine's association with an Instance Type.

machineAssociationId path parameter has been renamed to machineId. The path parameter will continue to accept both Machine ID and Machine/Instance Type ID until July 9th, 2026 00:00 UTC. After that time, Machine/Instance Type ID will no longer be accepted.

Org must have an Infrastructure Provider entity that owns the Instance Type and the Machine. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceTypeId required	string <uuid> ID of the Instance Type
machineAssociationId required	string Can be ID of the Machine (`machineId`) or ID of Machine/Instance Type Association (`machineAssociationId`). Use of `machineAssociationId` is now deprecated and will no longer be accepted after July 9th, 2026 00:00 UTC.

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Instance

Instance is a Machine provisioned with an Operating System by a Tenant and attached to one or more VPC Prefixes or Subnets.

Deprecation history:

sshUrl was deprecated in favor of serialConsoleUrl and was removed on April 25th, 2023 0:00 UTC. Please use serialConsoleUrl instead.
instanceSubnets was deprecated in favor of interfaces and was removed on May 10th, 2023 0:00 UTC. Please use interfaces instead.
sshkeygroups was deprecated in favor of sshKeyGroups and was removed on September 4th, 2025 0:00 UTC. Please use sshKeyGroups instead.

Retrieve all Instances

Get all Instances for Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

infrastructureProviderId	string <uuid> Filter by Infrastructure Provider ID
siteId	string <uuid> Filter by Site ID. Can be specified multiple times to filter on more than one site.
vpcId	string <uuid> Filter by VPC ID. Can be specified multiple times to filter on more than one VPC.
instanceTypeId	string <uuid> Filter by instance type ID. Can be specified multiple times to filter on more than one instance type.
operatingSystemId	string <uuid> Filter by operating system ID. Can be specified multiple times to filter on more than one operating system.
machineId	string Filter by machine ID. Can be specified multiple times to filter on more than one machine.
name	string Filter by Instance name
status	string Filter Instances by Status. Can be specified multiple times to filter on more than one status.
ipAddress	string Filter by IP address. Can be specified multiple times to filter on more than one IP address.
query	string Search for matches across all Sites. Input will be matched against name, description, status, and labels fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" "InstanceType" "Allocation" "VPC" "Machine" "OperatingSystem" "NetworkSecurityGroup" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "MACHINE_ID_ASC" "MACHINE_ID_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "INSTANCE_TYPE_NAME_ASC" "INSTANCE_TYPE_NAME_DESC" "HAS_INFINIBAND_ASC" "HAS_INFINIBAND_DESC" Ordering for pagination query
networkSecurityGroupId	string Filter by NetworkSecurityGroup ID. Can be specified multiple times to filter on more than one Network Security Group.

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Instance
name	string [ 2 .. 256 ] characters Name for the Instance
description	string Description for the Instance
tenantId	string <uuid> ID of the Tenant the Instance belongs to
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that owns the Site where the Instance is located
siteId	string <uuid> ID of the Site where the Instance is located
instanceTypeId	string <uuid>
vpcId	string <uuid>
secondaryVpcIds	Array of strings <uuid> [ items <uuid > ] IDs of VPCs attached to the Instance through non-primary interfaces
machineId	string or null
operatingSystemId	string <uuid>
networkSecurityGroupId	string or null
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
networkSecurityGroupInherited	boolean Indicates if the Network Security Group is inherited from VPC
controllerInstanceId	string or null <uuid>
ipxeScript	string or null
alwaysBootWithCustomIpxe	boolean Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabled	boolean Indicates whether the Phone Home service should be enabled or disabled for Instance
userData	string or null
	object (Labels) <= 10 properties
isUpdatePending	boolean Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrl	string or null Serial Console URL for the Instance. Format: ssh://@siteSerialConsoleHostname
	Array of objects (Interface)
	Array of objects (InfiniBandInterface)
	Array of objects (NVLinkInterface)
	Array of objects (DpuExtensionServiceDeployment) DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] IDs of SSH Key Groups associated with this Instance
	Array of objects (SshKeyGroup) IDs of SSH Key Groups associated with this Instance
tpmEkCertificate	string or null base64 encoded TPM EK Certificate associated with this Instance
status	string (InstanceStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Updating" "Rebooting" "Terminating" "Error" Status values for Instance objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

Example

example-1

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-monitor-1",
"description": "Node for monitoring Spark",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": "158fc2bc-f2fb-4e1f-a5a4-2211062d14df",
"ipxeScript": null,
"alwaysBootWithCustomIpxe": false,
"userData": null,
"labels": {"region": "portland",
"env": "staging"
},
"isUpdatePending": false,
"networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e,",
"networkSecurityGroupPropagationDetails": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"detailedStatus": "Partial",
"status": "Synchronizing",
"details": "",
"unpropagatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"relatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"networkSecurityGroupInherited": false,
"serialConsoleUrl": "ssh://user@carbide.acme.com",
"interfaces": [{"id": "64d2028c-ae87-4069-a624-66089d957ef9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true,
"device": null,
"deviceInstance": null,
"virtualFunctionId": null,
"macAddress": "2F-FC-34-AE-9C-2A",
"ipAddresses": ["200.32.11.190"
],
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"infinibandInterfaces": [{"id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"nvLinkInterfaces": [{"id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 0,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "c0ae6ec4-9a77-4358-baad-ee8cc3332c91",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 1,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "aa44ff62-d86b-4db6-9fa4-90a19b05be01",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 2,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "a403d1ca-2c07-410a-9678-3eb44d570ad9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 3,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"dpuExtensionServiceDeployments": [ ],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"sshKeyGroups": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"status": "Syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
"status": "Ready",
"statusHistory": [{"status": "BootCompleted",
"message": "The Instance successfully completed boot up",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"attribute": "sshkeygroups",
"replacedBy": "sshKeyGroups",
"takeActionBy": "2025-09-04T00:00:00Z",
"notice": "'sshkeygroups' is being deprecated in favor of 'sshKeyGroups'. Please take action prior to the specified date."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create an Instance

Create an Instance for Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters Name of the Instance
description	string or null <= 1024 characters Description of the Instance, optional
tenantId required	string <uuid> ID of the Tenant creating the Instance
instanceTypeId	string <uuid> ID of the Instance Type to use for Instance
machineId	string ID of of specific Machine to use for Instance. Requires Targeted Instance Creation capability enabled for Tenant
vpcId required	string <uuid> ID of the VPC the Instance should belong to
secondaryVpcIds	Array of strings <uuid> unique [ items <uuid > ] IDs of additional VPCs the Instance should attach to through non-primary interfaces. This field may only be specified when every entry in `interfaces` uses `vpcPrefixId`. IDs must be unique, must be valid UUIDs, and must not include the primary `vpcId`.
userData	string or null Can only be specified if allowOverride is set to true in Operating System
operatingSystemId	string or null <uuid> Must be specified if iPXE Script field is empty
networkSecurityGroupId	string or null
ipxeScript	string or null Override iPXE script specified in OS, must be specified if Operating System is not specified
alwaysBootWithCustomIpxe	boolean When set to true, the iPXE script specified by OS or overridden here will always be run when rebooting the Instance. OS must be of iPXE type.
phoneHomeEnabled	boolean When set to true, the Instance will be enabled with the Phone Home service.
	object (Labels) <= 10 properties
required	Array of objects (InterfaceCreateRequest) At least one interface must be specified. Either Subnet or VPC Prefix interfaces allowed. Only one of the Subnets or VPC Prefixes can be attached over Physical interface. If only one Subnet is specified, then it will be attached over physical interface regardless of the value of isPhysical. In case of VPC Prefix, isPhysical will always be true
	Array of objects (InfiniBandInterfaceCreateRequest) Associate one or more Partitions with this Instance
	Array of objects (DpuExtensionServiceDeploymentRequest) DPU Extension Services to deploy to the DPUs of this Instance
	Array of objects (NVLinkInterfaceCreateRequest) Define Interfaces to associate Instance GPUs with NVLink Logical Partitions. A subset of GPUs may be specified (it is not required to include all GPUs). Each item references one GPU index (`deviceInstance`) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] Specify list of SSH Key Group IDs that will provide Serial over LAN access
allowUnhealthyMachine	boolean Set to true in order to target Machines are in maintenance or have health alerts preventing regular provision flow. Requires Targeted Instance Creation capability enabled for Tenant

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Instance
name	string [ 2 .. 256 ] characters Name for the Instance
description	string Description for the Instance
tenantId	string <uuid> ID of the Tenant the Instance belongs to
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that owns the Site where the Instance is located
siteId	string <uuid> ID of the Site where the Instance is located
instanceTypeId	string <uuid>
vpcId	string <uuid>
secondaryVpcIds	Array of strings <uuid> [ items <uuid > ] IDs of VPCs attached to the Instance through non-primary interfaces
machineId	string or null
operatingSystemId	string <uuid>
networkSecurityGroupId	string or null
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
networkSecurityGroupInherited	boolean Indicates if the Network Security Group is inherited from VPC
controllerInstanceId	string or null <uuid>
ipxeScript	string or null
alwaysBootWithCustomIpxe	boolean Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabled	boolean Indicates whether the Phone Home service should be enabled or disabled for Instance
userData	string or null
	object (Labels) <= 10 properties
isUpdatePending	boolean Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrl	string or null Serial Console URL for the Instance. Format: ssh://@siteSerialConsoleHostname
	Array of objects (Interface)
	Array of objects (InfiniBandInterface)
	Array of objects (NVLinkInterface)
	Array of objects (DpuExtensionServiceDeployment) DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] IDs of SSH Key Groups associated with this Instance
	Array of objects (SshKeyGroup) IDs of SSH Key Groups associated with this Instance
tpmEkCertificate	string or null base64 encoded TPM EK Certificate associated with this Instance
status	string (InstanceStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Updating" "Rebooting" "Terminating" "Error" Status values for Instance objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

Example

With Subnet/InfiniBand Interfaces & iPXE Override

{"name": "spark-monitor-1",
"description": "Node for monitoring Spark",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"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\nshell",
"alwaysBootWithCustomIpxe": true,
"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",
"labels": {"region": "portland",
"env": "staging"
},
"interfaces": [{"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true
}
],
"infinibandInterfaces": [{"partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null
}
],
"nvLinkInterfaces": [{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 0
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 1
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 2
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 3
}
],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

201
400
403

Content type

application/json

Example

With iPXE override and Ethernet/InfiniBand Interfaces

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-monitor-1",
"description": "Node for monitoring Spark",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": null,
"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\nshell",
"alwaysBootWithCustomIpxe": true,
"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",
"labels": {"region": "portland",
"env": "staging"
},
"isUpdatePending": false,
"serialConsoleUrl": "ssh://user@carbide.acme.com",
"interfaces": [{"id": "64d2028c-ae87-4069-a624-66089d957ef9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true,
"virtualFunctionId": null,
"macAddress": null,
"ipAddresses": [ ],
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"infinibandInterfaces": [{"id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"nvLinkInterfaces": [{"id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 0,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"dpuExtensionServiceDeployments": [ ],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"sshKeyGroups": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"status": "Syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"attribute": "sshkeygroups",
"replacedBy": "sshKeyGroups",
"takeActionBy": "2025-09-04T00:00:00Z",
"notice": "'sshkeygroups' is being deprecated in favor of 'sshKeyGroups'. Please take action prior to the specified date."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Batch Create Instances

Batch create multiple Instances for Tenant with NVLink domain-aware machine allocation.

This endpoint creates multiple instances in a single atomic transaction. All instances share the same configuration (interfaces, OS, SSH keys, etc.) but are assigned different machines.

When topologyOptimized is true (default), all instances must be allocated on machines within the same NVLink domain. If insufficient machines are available in a single NVLink domain, the request will fail.

When topologyOptimized is false, instances can be spread across different NVLink domains.

Instance names are automatically generated using the namePrefix with a random 6-character suffix (e.g., "worker" becomes "worker-abc123", "worker-def456").

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

namePrefix required	string [ 2 .. 240 ] characters Prefix for instance names. Instances will be named with this prefix followed by a random 6-character suffix (e.g., "worker" becomes "worker-abc123")
count required	integer [ 2 .. 18 ] Number of instances to create in this batch. Minimum 2, maximum 18 (limited by topology domain size)
description	string or null <= 1024 characters Description applied to all instances in the batch, optional
tenantId required	string <uuid> ID of the Tenant creating the Instances
instanceTypeId required	string <uuid> ID of the Instance Type to use for all Instances in the batch
vpcId required	string <uuid> ID of the VPC the Instances should belong to
secondaryVpcIds	Array of strings <uuid> unique [ items <uuid > ] IDs of additional VPCs the Instances should attach to through non-primary interfaces. This field may only be specified when every entry in `interfaces` uses `vpcPrefixId`. IDs must be unique, must be valid UUIDs, and must not include the primary `vpcId`.
userData	string or null User data applied to all instances. Can only be specified if allowOverride is set to true in Operating System
operatingSystemId	string or null <uuid> Must be specified if iPXE Script field is empty
networkSecurityGroupId	string or null <uuid> ID of a Network Security Group to attach to all instances
ipxeScript	string or null Override iPXE script specified in OS, must be specified if Operating System is not specified
alwaysBootWithCustomIpxe	boolean When set to true, the iPXE script specified by OS or overridden here will always be run when rebooting the Instances. OS must be of iPXE type.
phoneHomeEnabled	boolean When set to true, the Instances will be enabled with the Phone Home service.
	object (Labels) <= 10 properties
required	Array of objects (InterfaceCreateRequest) Interface configuration shared across all instances. At least one interface must be specified. Either Subnet or VPC Prefix interfaces allowed, only one of the Subnets or VPC Prefixes can be attached over Physical interface. Interface `ipAddress` is not supported for batch instance creation requests.
	Array of objects (InfiniBandInterfaceCreateRequest) InfiniBand interface configuration shared across all instances
	Array of objects (DpuExtensionServiceDeploymentRequest) DPU Extension Services to deploy to all instances in the batch
	Array of objects (NVLinkInterfaceCreateRequest) NVLink interface configuration shared across all instances. A subset of GPUs may be specified. Each item references one GPU index (`deviceInstance`) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] SSH Key Group IDs that will provide Serial over LAN access to all instances
topologyOptimized	boolean Default: true When true (default), all instances must be allocated on machines within the same NVLink domain. When false, instances can be spread across different NVLink domains.

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the Instance
name	string [ 2 .. 256 ] characters Name for the Instance
description	string Description for the Instance
tenantId	string <uuid> ID of the Tenant the Instance belongs to
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that owns the Site where the Instance is located
siteId	string <uuid> ID of the Site where the Instance is located
instanceTypeId	string <uuid>
vpcId	string <uuid>
secondaryVpcIds	Array of strings <uuid> [ items <uuid > ] IDs of VPCs attached to the Instance through non-primary interfaces
machineId	string or null
operatingSystemId	string <uuid>
networkSecurityGroupId	string or null
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
networkSecurityGroupInherited	boolean Indicates if the Network Security Group is inherited from VPC
controllerInstanceId	string or null <uuid>
ipxeScript	string or null
alwaysBootWithCustomIpxe	boolean Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabled	boolean Indicates whether the Phone Home service should be enabled or disabled for Instance
userData	string or null
	object (Labels) <= 10 properties
isUpdatePending	boolean Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrl	string or null Serial Console URL for the Instance. Format: ssh://@siteSerialConsoleHostname
	Array of objects (Interface)
	Array of objects (InfiniBandInterface)
	Array of objects (NVLinkInterface)
	Array of objects (DpuExtensionServiceDeployment) DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] IDs of SSH Key Groups associated with this Instance
	Array of objects (SshKeyGroup) IDs of SSH Key Groups associated with this Instance
tpmEkCertificate	string or null base64 encoded TPM EK Certificate associated with this Instance
status	string (InstanceStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Updating" "Rebooting" "Terminating" "Error" Status values for Instance objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

Example

Topology-optimized batch with InfiniBand

{"namePrefix": "gpu-worker",
"count": 4,
"description": "GPU worker nodes for distributed training",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"topologyOptimized": true,
"interfaces": [{"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true
}
],
"infinibandInterfaces": [{"partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true
}
],
"nvLinkInterfaces": [{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 0
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 1
}
],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

201
400
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "worker-abc123",
"description": "Worker node for distributed training",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": null,
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "85c5e7b2-89f1-4e32-9d3a-8e1f5a2c7d90",
"name": "worker-def456",
"description": "Worker node for distributed training",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "gn200iu5w5ndf3rtukol9081ook4jf7fdfl5nuok38qfb5lsf6hub50kh1h",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": null,
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve Instance

Get an Instance by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string <uuid> ID of the Instance

query Parameters

includeRelation

string

Enum: "InfrastructureProvider" "Tenant" "Site" "InstanceType" "Allocation" "VPC" "OperatingSystem" "NetworkSecurityGroup"

Related entity to expand

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Instance
name	string [ 2 .. 256 ] characters Name for the Instance
description	string Description for the Instance
tenantId	string <uuid> ID of the Tenant the Instance belongs to
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that owns the Site where the Instance is located
siteId	string <uuid> ID of the Site where the Instance is located
instanceTypeId	string <uuid>
vpcId	string <uuid>
secondaryVpcIds	Array of strings <uuid> [ items <uuid > ] IDs of VPCs attached to the Instance through non-primary interfaces
machineId	string or null
operatingSystemId	string <uuid>
networkSecurityGroupId	string or null
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
networkSecurityGroupInherited	boolean Indicates if the Network Security Group is inherited from VPC
controllerInstanceId	string or null <uuid>
ipxeScript	string or null
alwaysBootWithCustomIpxe	boolean Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabled	boolean Indicates whether the Phone Home service should be enabled or disabled for Instance
userData	string or null
	object (Labels) <= 10 properties
isUpdatePending	boolean Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrl	string or null Serial Console URL for the Instance. Format: ssh://@siteSerialConsoleHostname
	Array of objects (Interface)
	Array of objects (InfiniBandInterface)
	Array of objects (NVLinkInterface)
	Array of objects (DpuExtensionServiceDeployment) DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] IDs of SSH Key Groups associated with this Instance
	Array of objects (SshKeyGroup) IDs of SSH Key Groups associated with this Instance
tpmEkCertificate	string or null base64 encoded TPM EK Certificate associated with this Instance
status	string (InstanceStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Updating" "Rebooting" "Terminating" "Error" Status values for Instance objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-monitor-1",
"description": "Node for monitoring Spark",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": null,
"ipxeScript": null,
"alwaysBootWithCustomIpxe": false,
"userData": null,
"networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e",
"networkSecurityGroupPropagationDetails": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"detailedStatus": "Partial",
"status": "Synchronizing",
"details": "",
"unpropagatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"relatedInstanceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"networkSecurityGroupInherited": false,
"labels": {"region": "portland",
"env": "staging"
},
"isUpdatePending": false,
"serialConsoleUrl": "ssh://user@carbide.acme.com",
"interfaces": [{"id": "64d2028c-ae87-4069-a624-66089d957ef9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true,
"virtualFunctionId": null,
"macAddress": "2F-FC-34-AE-9C-2A",
"ipAddresses": ["200.32.11.190"
],
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"infinibandInterfaces": [{"id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"nvLinkInterfaces": [{"id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 0,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "c0ae6ec4-9a77-4358-baad-ee8cc3332c91",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 1,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "aa44ff62-d86b-4db6-9fa4-90a19b05be01",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 2,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "a403d1ca-2c07-410a-9678-3eb44d570ad9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
"deviceInstance": 3,
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"dpuExtensionServiceDeployments": [{"id": "3951ec37-d78f-4ad7-92e1-3fdc76ccf246",
"dpuExtensionService": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"serviceType": "KubernetesPod",
"latestVersion": "V1-T1761856992374052",
"status": "Ready"
},
"version": "V1-T1761856992374052",
"status": "Running",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"sshKeyGroups": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"status": "Syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
"status": "Pending",
"statusHistory": [{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"attribute": "sshkeygroups",
"replacedBy": "sshKeyGroups",
"takeActionBy": "2025-09-04T00:00:00Z",
"notice": "'sshkeygroups' is being deprecated in favor of 'sshKeyGroups'. Please take action prior to the specified date."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete Instance

Delete an Instance by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string <uuid> ID of the Instance

Request Body schema: application/json

Optional request data to report health issues with the underlying Machine

	object (MachineHealthIssue) Information regarding issue with the underlying Machine experienced by Tenant
isRepairTenant	boolean or null Should be set to true for Tenants who are performing investigation/repairing the Machine. Otherwise omit or set to false

Responses

Request samples

Payload

Content type

application/json

{"machineHealthIssue": {"category": "Network",
"summary": "Machine has DPU connectivity error"
},
"isRepairTenant": false
}

Update Instance

Update an Instance by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string <uuid> ID of the Instance

Request Body schema: application/json

name	string or null [ 2 .. 256 ] characters Updated name for the Instance
description	string or null <= 1024 characters Updated description of the Instance
triggerReboot	boolean or null Trigger power cycle for Instance
rebootWithCustomIpxe	boolean or null When specified along with triggerReboot, the Instance will boot using the custom iPXE specified by OS. If Instance has alwaysBootWithCustomIpxe flag set then this value will be ignored.
applyUpdatesOnReboot	boolean or null When specified, any updates pending for the Instance e.g. DPU reprovisioning, will be applied on reboot
operatingSystemId	string or null The UUID of the desired operating system.
ipxeScript	string or null The iPXE script content to be used for booting.
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] Specify a new list of SSH Key Group IDs that will provide Serial over LAN and SSH access. This will overwrite an existing list.
networkSecurityGroupId	string or null
userData	string or null Any user-data to be sent to the booting OS. For example, cloud-init data.
alwaysBootWithCustomIpxe	boolean or null Whether the custom iPXE data should be used for every boot.
phoneHomeEnabled	boolean or null Indicates whether the Phone Home service should be enabled or disabled for Instance
	object (Labels) <= 10 properties Update labels of the Instance. The labels will be entirely replaced by those sent in the request. Any labels not included in the request will be removed. To retain existing labels, first fetch them and include them along with this request.
secondaryVpcIds	Array of strings <uuid> unique [ items <uuid > ] IDs of additional VPCs the Instance should attach to through non-primary interfaces. This field may only be specified when every entry in `interfaces` uses `vpcPrefixId`. IDs must be unique, must be valid UUIDs, and must not include the primary `vpcId`.
	Array of objects (InterfaceCreateRequest) Update Interfaces of the Instance
	Array of objects (InfiniBandInterfaceCreateRequest) Update InfiniBand Interfaces of the Instance
	Array of objects (NVLinkInterfaceCreateRequest) Update NVLink Interfaces of the Instance. A subset of GPUs may be specified. Each item references one GPU index (`deviceInstance`) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.
	Array of objects (DpuExtensionServiceDeploymentRequest) Updated set of DPU Extension Services to deploy to the DPUs of this Instance

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the Instance
name	string [ 2 .. 256 ] characters Name for the Instance
description	string Description for the Instance
tenantId	string <uuid> ID of the Tenant the Instance belongs to
infrastructureProviderId	string <uuid> ID of the Infrastructure Provider that owns the Site where the Instance is located
siteId	string <uuid> ID of the Site where the Instance is located
instanceTypeId	string <uuid>
vpcId	string <uuid>
secondaryVpcIds	Array of strings <uuid> [ items <uuid > ] IDs of VPCs attached to the Instance through non-primary interfaces
machineId	string or null
operatingSystemId	string <uuid>
networkSecurityGroupId	string or null
	object (NetworkSecurityGroupPropagationDetails) Propagation details for the attached Network Security Group
networkSecurityGroupInherited	boolean Indicates if the Network Security Group is inherited from VPC
controllerInstanceId	string or null <uuid>
ipxeScript	string or null
alwaysBootWithCustomIpxe	boolean Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabled	boolean Indicates whether the Phone Home service should be enabled or disabled for Instance
userData	string or null
	object (Labels) <= 10 properties
isUpdatePending	boolean Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrl	string or null Serial Console URL for the Instance. Format: ssh://@siteSerialConsoleHostname
	Array of objects (Interface)
	Array of objects (InfiniBandInterface)
	Array of objects (NVLinkInterface)
	Array of objects (DpuExtensionServiceDeployment) DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIds	Array of strings <uuid> [ items <uuid > ] IDs of SSH Key Groups associated with this Instance
	Array of objects (SshKeyGroup) IDs of SSH Key Groups associated with this Instance
tpmEkCertificate	string or null base64 encoded TPM EK Certificate associated with this Instance
status	string (InstanceStatus) Enum: "Pending" "Provisioning" "Configuring" "Ready" "Updating" "Rebooting" "Terminating" "Error" Status values for Instance objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "spark-monitor-1",
"description": "Spark Monitor Node 1",
"triggerReboot": true,
"rebootWithCustomIpxe": true,
"applyUpdatesOnReboot": true,
"sshKeyGroupIds": ["a7bf2f9c-12f0-4673-be47-12be6d9e16c8"
],
"labels": {"region": "portland",
"env": "staging"
},
"interfaces": [{"vpcPrefixId": "1f492faa-2963-4f21-aab5-9f00b2e40119",
"device": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"deviceInstance": 0,
"virtualFunctionId": null,
"isPhysical": true
},
{"vpcPrefixId": "1f3677dd-5794-4e57-b9b0-aebaf49b84fe",
"device": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"deviceInstance": 0,
"virtualFunctionId": 1,
"isPhysical": false
},
{"vpcPrefixId": "29e6f51b-145c-4f89-8c26-accaa8328398",
"device": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"deviceInstance": 0,
"virtualFunctionId": 2,
"isPhysical": false
}
],
"infinibandInterfaces": [{"partitionId": "550e8400-e29b-41d4-a716-446655440000",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true
},
{"partitionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 1,
"isPhysical": false
},
{"partitionId": "8b05d5c3-8de4-48c8-8d1c-399a8abc3ab8",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 2,
"isPhysical": false
}
],
"nvLinkInterfaces": [{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 0
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 1
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 2
},
{"nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
"deviceInstance": 3
}
],
"dpuExtensionServiceDeployments": [{"dpuExtensionServiceId": "3bddb7b4-0963-4278-b311-c212dc758357",
"version": "V1-T1761856992374052"
},
{"dpuExtensionServiceId": "cd4a8168-c206-430a-9a4b-bf7dbbac3b40",
"version": "V1-T1762294647497908"
}
]
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "spark-monitor-2",
"description": "Spark Monitor Node 1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
"vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
"controllerInstanceId": "158fc2bc-f2fb-4e1f-a5a4-2211062d14df",
"ipxeScript": null,
"alwaysBootWithCustomIpxe": false,
"userData": null,
"labels": {"region": "portland",
"env": "staging"
},
"isUpdatePending": false,
"serialConsoleUrl": "ssh://user@carbide.acme.com",
"interfaces": [{"id": "64d2028c-ae87-4069-a624-66089d957ef9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true,
"virtualFunctionId": null,
"macAddress": "2F-FC-34-AE-9C-2A",
"ipAddresses": ["200.32.11.190"
],
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"infinibandInterfaces": [{"id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"partitionId": "550e8400-e29b-41d4-a716-446655440000",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "3cc0206e-8ac9-4572-8f72-e1dd124c4351",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"partitionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 1,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "84a2cf1e-73fc-42f4-974e-33a4e9889eb9",
"instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"partitionId": "8b05d5c3-8de4-48c8-8d1c-399a8abc3ab8",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 2,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"dpuExtensionServiceDeployments": [{"id": "3951ec37-d78f-4ad7-92e1-3fdc76ccf246",
"dpuExtensionService": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"serviceType": "KubernetesPod",
"latestVersion": "V1-T1761856992374052",
"status": "Ready"
},
"version": "V1-T1761856992374052",
"status": "Running",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "60d3ad40-62c6-44ca-b6b1-74bc6dd04f1c",
"dpuExtensionService": {"id": "cd4a8168-c206-430a-9a4b-bf7dbbac3b40",
"name": "openssh-server",
"serviceType": "KubernetesPod",
"latestVersion": "V1-T1762294647497908",
"status": "Ready"
},
"version": "V1-T1762294647497908",
"status": "Running",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeyGroupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"sshKeyGroups": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"status": "Syncing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
"status": "Rebooting",
"statusHistory": [{"status": "Rebooting",
"message": "Reboot request received, processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"status": "Provisioning",
"message": "Instance is being provisioned on Site",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"deprecations": [{"attribute": "sshkeygroups",
"replacedBy": "sshKeyGroups",
"takeActionBy": "2025-09-04T00:00:00Z",
"notice": "'sshkeygroups' is being deprecated in favor of 'sshKeyGroups'. Please take action prior to the specified date."
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve Instance status history

Get Instance status history

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string ID of the Instance

query Parameters

pageNumber	integer Page number for pagination query
pageSize	integer Page size for pagination query
orderBy	string Ordering for pagination query

Responses

Response Headers
X-Pagination	string Pagination result in JSON format

Response Schema: application/json

Array

status	string
message	string
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve all Interfaces

Get all Interfaces for an Instance

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string ID of the Instance

query Parameters

status	string Filter Interfaces by Status
includeRelation	string Enum: "Instance" "Subnet" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> non-empty
instanceId	string <uuid>
subnetId	string or null <uuid>
vpcPrefixId	string or null <uuid>
isPhysical	boolean
device	string or null Name of the device to use
deviceInstance	integer or null Index of the device, used to identify which interface card to attache the Partition to
virtualFunctionId	integer or null Must be specified if isPhysical is false
macAddress	string or null
ipAddresses	Array of strings A list of IPv4 or IPv6 addresses
requestedIpAddress	string or null Explicitly requested IP address for the interface. This is only used for VPC Prefix based interfaces and is not valid for Subnet based interfaces. The least-significant host bit must be 1.
status	string (InterfaceStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Interface objects
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"isPhysical": true,
"virtualFunctionId": null,
"macAddress": "2F-FC-34-AE-9C-2A",
"ipAddresses": ["200.32.11.190"
],
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "d57b373a-5a59-4fa4-b080-50e9a1095aeb",
"vpcPrefixId": "26be5f71-3d51-487b-a940-6513c7725cfd",
"isPhysical": true,
"virtualFunctionId": null,
"macAddress": "2F-FC-34-AE-9C-2A",
"ipAddresses": ["200.32.11.190"
],
"status": "Pending",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve all Instance InfiniBand Interfaces

Get all InfiniBand Interfaces for an Instance

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string ID of the Instance

query Parameters

status	string Filter InfiniBand Interfaces by Status
includeRelation	string Enum: "Instance" "InfiniBandPartition" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> non-empty
instanceId	string <uuid>
partitionId	string <uuid> ID of the InfiniBand Partition associated with this interface
device	string Name of the InfiniBand device associated with this interface
deviceInstance	integer
isPhysical	boolean Indicates whether this is a physical interface
virtualFunctionId	integer or null
guid	string or null
status	string (InfiniBandInterfaceStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for InfiniBand Interface objects
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 0,
"isPhysical": true,
"virtualFunctionId": null,
"guid": "946dae0300339498",
"status": "Provisioning",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"partitionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"device": "MT2910 Family [ConnectX-7]",
"deviceInstance": 1,
"isPhysical": false,
"virtualFunctionId": 1,
"guid": "946dae0300339499",
"status": "Provisioning",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve all Instance NVLink Interfaces

Get all NVLink Interfaces for an Instance

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
instanceId required	string ID of the Instance

query Parameters

status	string Filter NVLink Interfaces by Status. Can be specified multiple times to filter on more than one status.
includeRelation	string Enum: "Instance" "NVLinkLogicalPartition" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> non-empty
instanceId	string <uuid>
nvLinkLogicalPartitionId	string <uuid> ID of the NVLink Logical Partition associated with this interface
nvLinkDomainId	string <uuid> ID of the NVLink Domain associated with this Interface
deviceInstance	integer Index of the device, used to identify the GPU associated with this Interface
gpuGuid	string Unique ID of the GPU
status	string (NVLinkInterfaceStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for NVLink Interface objects
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"nvLinkLogicalPartitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"nvLinkDomainId": "4b145552-0d8f-45ff-b652-eed105f93e50",
"deviceInstance": 0,
"gpuGuid": "5108732638879268442",
"status": "Ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "8a7c3b21-1ffc-4c78-9a00-2a6f3859d099",
"instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
"nvLinkLogicalPartitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
"nvLinkDomainId": "4b145552-0d8f-45ff-b652-eed105f93e50",
"deviceInstance": 1,
"gpuGuid": "5108732638879268443",
"status": "Provisioning",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Machine

Machine is a physical server that contains CPUs, GPUs, memory, storage, and networking hardware. Machines are the physical building blocks of a Site.

Retrieve all Machines

Get all Machines for Infrastructure Provider.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string Filter Machines by Site ID
id	string Filter Machines by ID. Can be specified multiple times to filter on more than one ID.
hasInstanceType	boolean Filter Machines that have been assigned an Instance Type.
instanceTypeId	string Filter Machines by Instance Type ID. Can be specified multiple times to filter on more than one Instance Type ID.
tenantId	string Filter Machines by ID of tenant of assigned instance. Can be specified multiple times to filter on more than one Tenant ID.
hasInstance	boolean Filter Machines that are assigned to an Instance. siteId must be specified when using this param.
isMissingOnSite	boolean Filter Machines that are missing on Site.
includeMetadata	boolean Include Machine metadata e.g. BMC, DPU, GPU and Interface data. Can only be requested by Provider.
status	string Filter Machines by Status. Can be specified multiple times to filter on more than one Status.
capabilityType	string Filter Machines by Capability Type
capabilityName	string Filter Machines by Capability Name. Can be specified multiple times to filter on more than one Capability Name.
hwSkuDeviceType	string Filter Machines by hardware SKU Device Type. Example values: "gpu", "cpu", "storage", "cache"
query	string Provide query to search for matches. Input will be matched against Machine ID, vendor, product name, hostname and status
includeRelation	string Enum: "InfrastructureProvider" "Site" "InstanceType" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ID_ASC" "ID_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string Unique ID of Machine
infrastructureProviderId	string <uuid> ID of the Provider that owns the Machine
siteId	string <uuid> ID of the Site the Machine belongs to
instanceTypeId	string or null <uuid> ID of the Instance Type, if assigned
instanceId	string or null <uuid> ID of the Instance if this Machine is assigned to one
tenantId	string or null <uuid> ID of the Tenant that owns the Instance if the Machine is assigned to one
controllerMachineId	string ID of the Machine at Site, now same as the primary ID
controllerMachineType	string Denotes architecture (x86 vs ARM) of the Machine
hwSkuDeviceType	string or null SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.
vendor	string Name of the vendor of the Machine
productName	string Product name of the Machine
serialNumber	string Serial number of the Machine, only visible to Provider
	Array of objects (MachineCapability)
	Array of objects (MachineInterface)
maintenanceMessage	string or null If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance
	object (MachineHealth) Describes results of various Machine health probes and alerts
	object (MachineMetadata) Only available to Providers. Returned if includeMetadata query param is specified. Otherwise attribute is omitted from response.
	object (Labels) <= 10 properties
status	string (MachineStatus) Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown" Status values for Machine objects
isUsableByTenant	boolean Indicates whether the machine is usable by or currently in use by a tenant.
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": null,
"instanceId": null,
"tenantId": null,
"controllerMachineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerMachineType": "x86_64",
"hwSkuDeviceType": "cpu",
"vendor": "Lenovo",
"productName": "ThinkSystem SR670 V2",
"serialNumber": "J1060ACR.D3KS2CS001G",
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{"type": "Memory",
"name": "Corsair Vengeance LPX",
"capacity": "32GB",
"count": 4
}
],
"machineInterfaces": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerInterfaceId": "ad3dac49-741d-4c1f-815c-c020127c532f",
"controllerSegmentId": "f2207a3c-1847-42e5-bf2c-cd015f87a2bc",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"hostname": "example.com",
"isPrimary": true,
"macAddress": "00:00:5e:00:53:af",
"ipAddresses": ["192.156.7.23",
"202.88.37.112"
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"maintenanceMessage": null,
"health": {"source": "aggregate-host-health",
"observedAt": null,
"successes": [{"id": "BgpDaemonEnabled",
"target": null
},
{"id": "BgpStats",
"target": null
},
{"id": "DhcpServer",
"target": null
},
{"id": "DpuDiskUtilizationCheck",
"target": null
},
{"id": "FanSpeed",
"target": "System Board Fan1A"
},
{"id": "PowerSupply",
"target": "PS1 Status"
},
{"id": "Temperature",
"target": "CPU1 Temp"
},
{"id": "Temperature",
"target": "System Board Exhaust Temp"
},
{"id": "Voltage",
"target": "CPU1 1P8 PG"
}
],
"alerts": [ ]
},
"labels": {"RackIdentifier": "GVX11F01C02",
"ServerName": "SITE1-C03-Server-02"
},
"status": "Ready",
"isUsableByTenant": true,
"statusHistory": [{"status": "Ready",
"message": "Machine is online and ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve a Machine

Org must have either an Infrastructure Provider entity or a Tenant entity.

If org has an Infrastructure Provider entity, then a user with FORGE_PROVIDER_ADMIN role can request details for any Machine on any Site owned by the Provider.

If org has a Tenant entity, then a user with FORGE_TENANT_ADMIN role can request details for any Machine associated with Tenant's active Instances.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
machineId required	string ID of the Machine

query Parameters

includeRelation	string Enum: "InfrastructureProvider" "Site" "InstanceType" Related entity to expand
includeMetadata	boolean Include Machine metadata e.g. BMC, DPU, GPU and Interface data. Can only be requested by Provider.

Responses

Response Schema: application/json

id	string Unique ID of Machine
infrastructureProviderId	string <uuid> ID of the Provider that owns the Machine
siteId	string <uuid> ID of the Site the Machine belongs to
instanceTypeId	string or null <uuid> ID of the Instance Type, if assigned
instanceId	string or null <uuid> ID of the Instance if this Machine is assigned to one
tenantId	string or null <uuid> ID of the Tenant that owns the Instance if the Machine is assigned to one
controllerMachineId	string ID of the Machine at Site, now same as the primary ID
controllerMachineType	string Denotes architecture (x86 vs ARM) of the Machine
hwSkuDeviceType	string or null SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.
vendor	string Name of the vendor of the Machine
productName	string Product name of the Machine
serialNumber	string Serial number of the Machine, only visible to Provider
	Array of objects (MachineCapability)
	Array of objects (MachineInterface)
maintenanceMessage	string or null If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance
	object (MachineHealth) Describes results of various Machine health probes and alerts
	object (MachineMetadata) Only available to Providers. Returned if includeMetadata query param is specified. Otherwise attribute is omitted from response.
	object (Labels) <= 10 properties
status	string (MachineStatus) Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown" Status values for Machine objects
isUsableByTenant	boolean Indicates whether the machine is usable by or currently in use by a tenant.
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

Example

Without Metadata

{"id": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "2e016c02-2c67-48aa-b289-5d3ca6320c52",
"instanceId": "59bdaaff-3998-4fd9-a140-8749beeb605e",
"tenantId": "99819e6e-4017-4021-9edd-ea1bdf4dbd59",
"controllerMachineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerMachineType": "x86_64",
"hwSkuDeviceType": "cpu",
"vendor": "Lenovo",
"productName": "ThinkSystem SR670 V2",
"serialNumber": "J1060ACR.D3KS2CS001G",
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{"type": "Memory",
"name": "Corsair Vengeance LPX",
"capacity": "32GB",
"count": 4
},
{"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2,
"deviceType": "DPU"
},
{"type": "Storage",
"name": "Dell Ent NVMe CM6 RI 1.92TB",
"capacity": "1.92TB",
"count": 2
},
{"type": "GPU",
"name": "NVIDIA A100 PCIe",
"capacity": "80GB",
"count": 2
},
{"type": "InfiniBand",
"name": "MT28908 Family [ConnectX-6]",
"vendor": "Mellanox Technologies",
"count": 2
}
],
"machineInterfaces": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerInterfaceId": "ad3dac49-741d-4c1f-815c-c020127c532f",
"controllerSegmentId": "f2207a3c-1847-42e5-bf2c-cd015f87a2bc",
"attachedDpuMachineID": "fm100dsg4ekcb4sdi6hkqn0iojhj18okrr8vct64luh8957lfe8e69vme20,",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"hostname": "example.com",
"isPrimary": true,
"macAddress": "00:00:5e:00:53:af",
"ipAddresses": ["192.156.7.23",
"202.88.37.112"
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"maintenanceMessage": null,
"health": {"source": "aggregate-host-health",
"observedAt": null,
"successes": [{"id": "BgpDaemonEnabled",
"target": null
},
{"id": "BgpStats",
"target": null
},
{"id": "DhcpServer",
"target": null
},
{"id": "DpuDiskUtilizationCheck",
"target": null
},
{"id": "FanSpeed",
"target": "System Board Fan1A"
},
{"id": "PowerSupply",
"target": "PS1 Status"
},
{"id": "Temperature",
"target": "CPU1 Temp"
},
{"id": "Temperature",
"target": "System Board Exhaust Temp"
},
{"id": "Voltage",
"target": "CPU1 1P8 PG"
}
],
"alerts": [ ]
},
"labels": {"RackIdentifier": "GVX11F01C02",
"ServerName": "SITE1-C03-Server-02"
},
"status": "Ready",
"isUsableByTenant": true,
"statusHistory": [{"status": "Ready",
"message": "Machine is online and ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Update Machine

Update a Machine

Instance Type attribute updates, maintenance attribute updates and labels updates must be specified in separate requests. They cannot be processed at the same time.

Some attributes can only be updated by Provider, while others can be updated by Provider or a Privileged Tenant.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
machineId required	string ID of the Machine

Request Body schema: application/json

instanceTypeId	string or null <uuid> [ 2 .. 256 ] characters Update the Instance Type of the Machine. Cannot be specified when clearing Instance Type. Can only be updated by Provider.
clearInstanceType	boolean or null Set to true to clear the existing Instance Type. Cannot be specified if Instance Type ID is specified. Can only be set by Provider.
setMaintenanceMode	boolean or null Set to `true` to enable maintenance mode and to `false` to disable maintenance mode. Can be set by Provider or Privileged Tenant.
maintenanceMessage	string or null [ 5 .. 256 ] characters Optional message describing the reason for moving Machine into maintenance mode. Can be updated by Provider or Privileged Tenant.
	object (Labels) <= 10 properties Machine labels will be overwritten, include existing labels to preserve them. Can be updated by Provider or Privileged Tenant.

Responses

Response Schema: application/json

id	string Unique ID of Machine
infrastructureProviderId	string <uuid> ID of the Provider that owns the Machine
siteId	string <uuid> ID of the Site the Machine belongs to
instanceTypeId	string or null <uuid> ID of the Instance Type, if assigned
instanceId	string or null <uuid> ID of the Instance if this Machine is assigned to one
tenantId	string or null <uuid> ID of the Tenant that owns the Instance if the Machine is assigned to one
controllerMachineId	string ID of the Machine at Site, now same as the primary ID
controllerMachineType	string Denotes architecture (x86 vs ARM) of the Machine
hwSkuDeviceType	string or null SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.
vendor	string Name of the vendor of the Machine
productName	string Product name of the Machine
serialNumber	string Serial number of the Machine, only visible to Provider
	Array of objects (MachineCapability)
	Array of objects (MachineInterface)
maintenanceMessage	string or null If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance
	object (MachineHealth) Describes results of various Machine health probes and alerts
	object (MachineMetadata) Only available to Providers. Returned if includeMetadata query param is specified. Otherwise attribute is omitted from response.
	object (Labels) <= 10 properties
status	string (MachineStatus) Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown" Status values for Machine objects
isUsableByTenant	boolean Indicates whether the machine is usable by or currently in use by a tenant.
	Array of objects (StatusDetail)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

Example

Update Instance Type

{"instanceTypeId": "2e016c02-2c67-48aa-b289-5d3ca6320c52"
}

Response samples

200

Content type

application/json

{"id": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"instanceTypeId": "2e016c02-2c67-48aa-b289-5d3ca6320c52",
"instanceId": "59bdaaff-3998-4fd9-a140-8749beeb605e",
"tenantId": "99819e6e-4017-4021-9edd-ea1bdf4dbd59",
"controllerMachineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerMachineType": "x86_64",
"hwSkuDeviceType": "cpu",
"vendor": "Lenovo",
"productName": "ThinkSystem SR670 V2",
"serialNumber": "J1060ACR.D3KS2CS001G",
"machineCapabilities": [{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"frequency": "3.0GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{"type": "Memory",
"name": "Corsair Vengeance LPX",
"capacity": "32GB",
"count": 4
}
],
"machineInterfaces": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"controllerInterfaceId": "ad3dac49-741d-4c1f-815c-c020127c532f",
"controllerSegmentId": "f2207a3c-1847-42e5-bf2c-cd015f87a2bc",
"subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
"hostname": "example.com",
"isPrimary": true,
"macAddress": "00:00:5e:00:53:af",
"ipAddresses": ["192.156.7.23",
"202.88.37.112"
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"maintenanceMessage": null,
"health": {"source": "aggregate-host-health",
"observedAt": null,
"successes": [{"id": "BgpDaemonEnabled",
"target": null
},
{"id": "BgpStats",
"target": null
},
{"id": "DhcpServer",
"target": null
},
{"id": "DpuDiskUtilizationCheck",
"target": null
},
{"id": "FanSpeed",
"target": "System Board Fan1A"
},
{"id": "PowerSupply",
"target": "PS1 Status"
},
{"id": "Temperature",
"target": "CPU1 Temp"
},
{"id": "Temperature",
"target": "System Board Exhaust Temp"
},
{"id": "Voltage",
"target": "CPU1 1P8 PG"
}
],
"alerts": [ ]
},
"labels": {"RackIdentifier": "GVX11F01C02",
"ServerName": "SITE1-C03-Server-02"
},
"status": "Ready",
"isUsableByTenant": true,
"statusHistory": [{"status": "Ready",
"message": "Machine is online and ready",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete a Machine from a Site

Org must have an Infrastructure Provider entity. Machine must belong to the Provider. User must have FORGE_PROVIDER_ADMIN authorization role. Machine must meet certain criteria to be eligible for deletion.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
machineId required	string ID of the Machine

Responses

Response samples

400
403
404
422
500

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

Retrieve Machine status history

Org must have either an Infrastructure Provider entity or a Tenant entity.

If org has an Infrastructure Provider entity, then a user with FORGE_PROVIDER_ADMIN role can request details for any Machine on any Site owned by the Provider.

If org has a Tenant entity, then a user with FORGE_TENANT_ADMIN role can request details for any Machine associated with Tenant's active Instances.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
machineId required	string ID of the Machine

query Parameters

pageNumber	integer Page number for pagination query
pageSize	integer Page size for pagination query
orderBy	string Ordering for pagination query

Responses

Response Headers
X-Pagination	string Pagination result in JSON format

Response Schema: application/json

Array

status	string
message	string
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Retrieve GPU stats for machines at a site

Returns GPU summary stats grouped by GPU name for machines at the specified site.

User must have FORGE_PROVIDER_ADMIN authorization role. The specified site must belong to the Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

Array

name	string GPU name from the MachineCapability record
gpus	integer Total number of GPUs (summation of all Machine GPU capability counts)
machines	integer Number of machines that have this GPU capability

Response samples

200
403

Content type

application/json

[{"name": "string",
"gpus": 0,
"machines": 0
}
]

Retrieve machine instance type assignment summary for a site

Returns machine counts grouped by assigned (has instance type) vs unassigned, broken down by status.

User must have FORGE_PROVIDER_ADMIN authorization role. The specified site must belong to the Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

	object (MachineStatusBreakdown) Machines that have been assigned to an instance type
	object (MachineStatusBreakdown) Machines that have not been assigned to any instance type

Response samples

200
403

Content type

application/json

{"assigned": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
},
"unassigned": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
}
}

Retrieve detailed per-instance-type machine stats for a site

Returns machine stats for each instance type including allocation details and tenant breakdown.

User must have FORGE_PROVIDER_ADMIN authorization role. The specified site must belong to the Provider.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the InstanceType
name	string Name of the InstanceType
	object (MachineStatusBreakdown) Machine counts broken down by status
allocated	integer Number of Machines of this Instance Type allocated to Tenants
maxAllocatable	integer Number of Ready Machines of this Instance Type available for additional allocation to Tenants
	object (MachineStatusBreakdown) Machine counts broken down by status
	Array of objects (InstanceTypeStats)

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"assignedMachineStats": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
},
"allocated": 0,
"maxAllocatable": 0,
"usedMachineStats": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
},
"tenants": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"allocated": 0,
"usedMachineStats": {"total": 0,
"initializing": 0,
"ready": 0,
"inUse": 0,
"error": 0,
"maintenance": 0,
"unknown": 0
},
"maxAllocatable": 0,
"allocations": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"total": 0
}
]
}
]
}
]

Retrieve all Machine Capabilities

Get all distinct Machine Capabilities across all Machines

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string Filter Capabilities by Machines from a particular Site
hasInstanceType	boolean Filter Capabilities by Machines that have an Instance Type
type	string Filter Capabilities by Type
name	string Filter Capabilities by Name
frequency	string Filter Capabilities by Frequency value
capacity	string Filter Capabilities by Capacity value
vendor	string Filter Capabilities by Vendor
inactiveDevices	string Filter Capabilities by Inactive Devices value. Since the value is an array, multiple query params should be specified in correct order in order to filter. For example, to filter for [1, 3], specify inactiveDevices=1&inactiveDevices=3
count	string Filter Capabilities by Count
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

type	string Enum: "CPU" "Memory" "Storage" "Network" "GPU" "InfiniBand" "DPU" Type of the Capability
name	string Name of the Capability component
frequency	string or null Frequency of the Capability component, if available
cores	integer or null Number of Cores in the Capability component, if applicable
threads	integer or null Number of Threads in the Capability component, if applicable
capacity	string or null Capacity of the Capability component, if applicable
vendor	string or null Vendor of the Capability component, if available
inactiveDevices	Array of integers A list of inactive devices
count	integer or null Count of the Capability component
deviceType	string or null Device Type of the Capability component, if available

Response samples

200
403

Content type

application/json

[{"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{"name": "Intel(R) Xeon(R) Platinum 8362 CPU @ 2.80GHz",
"cores": 32,
"threads": 64,
"count": 2
},
{"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2
},
{"type": "Storage",
"name": "Dell Ent NVMe v2 AGN RI U.2 1.92TB",
"capacity": "1.92TB",
"count": 2
},
{"type": "Storage",
"name": "Dell Ent NVMe CM6 RI 1.92TB",
"capacity": "1.92TB",
"count": 2
},
{"type": "InfiniBand",
"name": "MT28908 Family [ConnectX-6]",
"vendor": "Mellanox Technologies",
"count": 2
}
]

Machine Capability

Machine Capability defines the hardware capabilities of a Machine. Machine Capabilities can be used to group Machines into Instance Types.

Rack

Rack is a physical enclosure that contains a number of Machines. Racks are the physical building blocks of a Site.

Retrieve all Racks

Get all Racks for the specified Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string <uuid> ID of the Site to retrieve Racks from
includeComponents	boolean Include rack components in response
name	string Filter by rack name
manufacturer	string Filter by manufacturer
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "MANUFACTURER_ASC" "MANUFACTURER_DESC" "MODEL_ASC" "MODEL_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\":\"NAME_ASC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier of the Rack
name	string Name of the Rack
manufacturer	string Manufacturer of the Rack
model	string Model of the Rack
serialNumber	string Serial number of the Rack
description	string Description of the Rack
	object (RackLocation) Physical location of a Rack
	Array of objects (RackComponent) Components within the Rack. Only returned when includeComponents is true.

Response samples

200
403

Content type

application/json

[{"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Rack-01",
"manufacturer": "Dell",
"model": "PowerEdge R750",
"serialNumber": "SN-RACK-001",
"description": "Primary compute rack",
"location": {"region": "us-east-1",
"datacenter": "DC-01",
"room": "Room-A",
"position": "A1"
},
"components": [{"id": "660e8400-e29b-41d4-a716-446655440001",
"componentId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"type": "ComponentTypeCompute",
"name": "Server-01",
"serialNumber": "SN-SRV-001",
"manufacturer": "Dell",
"firmwareVersion": "2.1.0",
"slotId": 1,
"trayIdx": 0,
"hostId": 0,
"bmcs": [{"type": "BmcTypeHost",
"macAddress": "AA:BB:CC:DD:EE:01",
"ipAddress": "10.0.0.101"
}
],
"powerState": "on"
}
]
}
]

Retrieve a Rack

Get a Rack by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Rack

query Parameters

siteId required	string <uuid> ID of the Site
includeComponents	boolean Include rack components in response

Responses

Response Schema: application/json

id	string <uuid> Unique identifier of the Rack
name	string Name of the Rack
manufacturer	string Manufacturer of the Rack
model	string Model of the Rack
serialNumber	string Serial number of the Rack
description	string Description of the Rack
	object (RackLocation) Physical location of a Rack
	Array of objects (RackComponent) Components within the Rack. Only returned when includeComponents is true.

Response samples

200
403
404

Content type

application/json

{"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Rack-01",
"manufacturer": "Dell",
"model": "PowerEdge R750",
"serialNumber": "SN-RACK-001",
"description": "Primary compute rack",
"location": {"region": "us-east-1",
"datacenter": "DC-01",
"room": "Room-A",
"position": "A1"
},
"components": [{"id": "660e8400-e29b-41d4-a716-446655440001",
"componentId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"type": "ComponentTypeCompute",
"name": "Server-01",
"serialNumber": "SN-SRV-001",
"manufacturer": "Dell",
"firmwareVersion": "2.1.0",
"slotId": 1,
"trayIdx": 0,
"hostId": 0,
"bmcs": [{"type": "BmcTypeHost",
"macAddress": "AA:BB:CC:DD:EE:01",
"ipAddress": "10.0.0.101"
}
],
"powerState": "on"
}
]
}

Validate Racks

Validate Rack components by comparing expected vs actual state.

If no filter is specified, validates all racks in the Site. Filters can narrow the scope to specific racks by name or manufacturer.

Compares the expected component configuration against the actual state. Returns a detailed diff report showing missing, extra, and drifted components.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string <uuid> ID of the Site
name	string Filter racks by name
manufacturer	string Filter racks by manufacturer

Responses

Response Schema: application/json

	Array of objects (ComponentDiff) List of component differences found during validation
totalDiffs	integer Total number of component differences found
missingCount	integer Number of components expected but missing from the source system
unexpectedCount	integer Number of components found in the source system but not expected
driftCount	integer Number of components present in both but with field differences
matchCount	integer Number of components that match between expected and actual

Response samples

200
400
403

Content type

application/json

Example

example-no-diffs

{"diffs": [ ],
"totalDiffs": 0,
"missingCount": 0,
"unexpectedCount": 0,
"driftCount": 0,
"matchCount": 10
}

Validate a Rack

Validate a Rack's components by comparing expected vs actual state.

Compares the rack's expected component configuration against the actual state. Returns a detailed diff report showing missing, extra, and drifted components.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Rack

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

	Array of objects (ComponentDiff) List of component differences found during validation
totalDiffs	integer Total number of component differences found
missingCount	integer Number of components expected but missing from the source system
unexpectedCount	integer Number of components found in the source system but not expected
driftCount	integer Number of components present in both but with field differences
matchCount	integer Number of components that match between expected and actual

Response samples

200
400
403

Content type

application/json

Example

example-no-diffs

{"diffs": [ ],
"totalDiffs": 0,
"missingCount": 0,
"unexpectedCount": 0,
"driftCount": 0,
"matchCount": 5
}

Power control Racks

Power control Racks with optional filters. If no filter is specified, targets all racks in the Site.

Supported power states: on, off, cycle, forceoff, forcecycle.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
	object (RackFilter) Filter criteria for selecting racks in batch operations. If omitted or empty, all racks in the site are targeted.
state required	string Enum: "on" "off" "cycle" "forceoff" "forcecycle" Target power state

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the power control operation (one per rack)

Request samples

Payload

Content type

application/json

Example

power-off-all

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"state": "off"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
]
}

Power control a Rack

Power control a Rack identified by Rack UUID.

Supported power states: on, off, cycle, forceoff, forcecycle.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Rack

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
state required	string Enum: "on" "off" "cycle" "forceoff" "forcecycle" Power control state to apply: `on`: Power on the target(s) `off`: Graceful power off `cycle`: Graceful power cycle (restart) `forceoff`: Forced power off (immediate) `forcecycle`: Forced power cycle (immediate restart)

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the power control operation (one per rack)

Request samples

Payload

Content type

application/json

Example

power-on

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"state": "on"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Firmware update Racks

Update firmware on Racks with optional name filter. If no filter is specified, targets all racks in the Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
	object (RackFilter) Filter criteria for selecting racks in batch operations. If omitted or empty, all racks in the site are targeted.
version	string Target firmware version.

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the firmware update operation

Request samples

Payload

Content type

application/json

Example

all-racks-latest

{"siteId": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
]
}

Firmware update a Rack

Update firmware on a Rack identified by Rack UUID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Rack

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
version	string Target firmware version.

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the firmware update operation

Request samples

Payload

Content type

application/json

Example

with-version

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"version": "24.11.0"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Bring up Racks

Bring up Racks with optional name filter. If no filter is specified, targets all racks in the Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
	object (RackFilter) Filter criteria for selecting racks in batch operations. If omitted or empty, all racks in the site are targeted.
description	string Optional description for the bring up operation

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the bring up operation (one per rack)

Request samples

Payload

Content type

application/json

Example

all-racks

{"siteId": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
]
}

Bring up a Rack

Bring up a Rack identified by Rack UUID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Rack

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
description	string Optional description for the bring up operation

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the bring up operation (one per rack)

Request samples

Payload

Content type

application/json

Example

basic

{"siteId": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Retrieve a Task

Get a Task by UUID.

Tasks are site-scoped; siteId must be the Site where the task was created. Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> UUID of the Task

query Parameters

siteId

required

string <uuid>

ID of the Site that owns the task (tasks are site-scoped).

Responses

Response Schema: application/json

id	string <uuid> Unique identifier of the task.
status	string Enum: "Unknown" "Pending" "Waiting" "Running" "Succeeded" "Failed" "Terminated" Current state of the task.
description	string Human-readable description provided when the task was created.
message	string Optional status or error message describing the current state or result.
started	string <date-time> Timestamp when the task started execution.
finished	string <date-time> Timestamp when the task finished (succeeded, failed or terminated).
created	string <date-time> Timestamp when the task was created.
updated	string <date-time> Timestamp when the task was last updated.

Response samples

200
400
403
404

Content type

application/json

{"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "Running",
"description": "Power on rack components",
"message": "Processing 3 of 5 components"
}

Tray

Tray represents a component within a Rack.

Retrieve all Trays

Get all Trays (components) for the specified Site.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Filter constraints:

rackId and rackName are mutually exclusive
rackId/rackName cannot be combined with id/componentId (rack-level vs component-level targeting)
componentId requires type to be specified

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string <uuid> ID of the Site to retrieve Trays from
rackId	string <uuid> Filter by Rack ID
rackName	string Filter by Rack name
type	string Enum: "compute" "switch" "powershelf" Filter by tray type
componentId	string Filter by component ID. Can be specified multiple times to filter on more than one component ID. Requires 'type' parameter.
id	string <uuid> Filter by tray UUID. Can be specified multiple times to filter on more than one tray ID.
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "MANUFACTURER_ASC" "MANUFACTURER_DESC" "MODEL_ASC" "MODEL_DESC" "TYPE_ASC" "TYPE_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\":\"NAME_ASC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier of the Tray
componentId	string ID of the component
type	string Enum: "compute" "switch" "powershelf" Type of the tray
name	string Name of the tray
manufacturer	string Manufacturer of the tray
model	string Model of the tray
serialNumber	string Serial number of the tray
description	string Description of the tray
firmwareVersion	string Firmware version of the tray
powerState	string Current power state of the tray
	object (TrayPosition) Position of a tray within a rack
	Array of objects (BMCInfo) BMC (Baseboard Management Controller) entries for the tray
rackId	string <uuid> ID of the rack this tray belongs to

Response samples

200
403

Content type

application/json

[{"id": "660e8400-e29b-41d4-a716-446655440001",
"componentId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"type": "compute",
"name": "compute-tray-1",
"manufacturer": "NVIDIA",
"model": "GB200",
"serialNumber": "TSN001",
"description": "Compute tray in slot 1",
"firmwareVersion": "2.1.0",
"powerState": "on",
"position": {"slotId": 1,
"trayIdx": 0,
"hostId": 1
},
"rackId": "550e8400-e29b-41d4-a716-446655440000"
}
]

Retrieve a Tray

Get a Tray by ID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Tray

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

id	string <uuid> Unique identifier of the Tray
componentId	string ID of the component
type	string Enum: "compute" "switch" "powershelf" Type of the tray
name	string Name of the tray
manufacturer	string Manufacturer of the tray
model	string Model of the tray
serialNumber	string Serial number of the tray
description	string Description of the tray
firmwareVersion	string Firmware version of the tray
powerState	string Current power state of the tray
	object (TrayPosition) Position of a tray within a rack
	Array of objects (BMCInfo) BMC (Baseboard Management Controller) entries for the tray
rackId	string <uuid> ID of the rack this tray belongs to

Response samples

200
403
404

Content type

application/json

{"id": "660e8400-e29b-41d4-a716-446655440001",
"componentId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
"type": "compute",
"name": "compute-tray-1",
"manufacturer": "NVIDIA",
"model": "GB200",
"serialNumber": "TSN001",
"description": "Compute tray in slot 1",
"firmwareVersion": "2.1.0",
"powerState": "on",
"position": {"slotId": 1,
"trayIdx": 0,
"hostId": 1
},
"rackId": "550e8400-e29b-41d4-a716-446655440000"
}

Validate Trays

Validate Tray components by comparing expected vs actual state.

If no filter is specified, validates all trays in the Site. Use rackId/rackName to scope to a specific rack, and name/manufacturer/type to filter by tray attributes.

Compares the expected component configuration against the actual state. Returns a detailed diff report showing missing, extra, and drifted components.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId required	string <uuid> ID of the Site
rackId	string <uuid> Scope to a specific Rack by ID (mutually exclusive with rackName)
rackName	string Scope to a specific Rack by name (mutually exclusive with rackId)
name	string Filter trays by name
manufacturer	string Filter trays by manufacturer
type	string Enum: "compute" "switch" "powershelf" Filter trays by type
componentId	string Filter by external component ID (requires type; mutually exclusive with rackId/rackName; use repeated params for multiple values)

Responses

Response Schema: application/json

	Array of objects (ComponentDiff) List of component differences found during validation
totalDiffs	integer Total number of component differences found
missingCount	integer Number of components expected but missing from the source system
unexpectedCount	integer Number of components found in the source system but not expected
driftCount	integer Number of components present in both but with field differences
matchCount	integer Number of components that match between expected and actual

Response samples

200
400
403

Content type

application/json

{"diffs": [ ],
"totalDiffs": 0,
"missingCount": 0,
"unexpectedCount": 0,
"driftCount": 0,
"matchCount": 10
}

Validate a Tray

Validate a Tray by comparing expected vs actual state.

Compares the expected component configuration against the actual state. Returns a detailed diff report showing missing, extra, and drifted components.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Tray

query Parameters

siteId

required

string <uuid>

ID of the Site

Responses

Response Schema: application/json

	Array of objects (ComponentDiff) List of component differences found during validation
totalDiffs	integer Total number of component differences found
missingCount	integer Number of components expected but missing from the source system
unexpectedCount	integer Number of components found in the source system but not expected
driftCount	integer Number of components present in both but with field differences
matchCount	integer Number of components that match between expected and actual

Response samples

200
400
403

Content type

application/json

{"diffs": [ ],
"totalDiffs": 0,
"missingCount": 0,
"unexpectedCount": 0,
"driftCount": 0,
"matchCount": 5
}

Power control Trays

Power control Trays with optional filters. If no filter is specified, targets all trays in the Site.

Supported power states: on, off, cycle, forceoff, forcecycle.

Filter constraints:

rackId and rackName are mutually exclusive
rackId/rackName cannot be combined with ids/componentIds (rack-level vs component-level targeting)
componentIds requires type to be specified

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
	object (TrayFilter) Filter criteria for selecting trays in batch operations. If omitted or empty, all trays in the site are targeted. Constraints: `rackId` and `rackName` are mutually exclusive. `rackId`/`rackName` cannot be combined with `ids`/`componentIds`. `componentIds` requires `type`.
state required	string Enum: "on" "off" "cycle" "forceoff" "forcecycle" Target power state

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the power control operation (one per rack)

Request samples

Payload

Content type

application/json

Example

power-on-all

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"state": "on"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Power control a Tray

Power control a Tray identified by Tray UUID.

Supported power states: on, off, cycle, forceoff, forcecycle.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Tray

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
state required	string Enum: "on" "off" "cycle" "forceoff" "forcecycle" Power control state to apply: `on`: Power on the target(s) `off`: Graceful power off `cycle`: Graceful power cycle (restart) `forceoff`: Forced power off (immediate) `forcecycle`: Forced power cycle (immediate restart)

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the power control operation (one per rack)

Request samples

Payload

Content type

application/json

Example

power-on

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"state": "on"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Firmware update Trays

Update firmware on Trays with optional filters. If no filter is specified, targets all trays in the Site.

Filter constraints:

rackId and rackName are mutually exclusive
rackId/rackName cannot be combined with ids/componentIds (rack-level vs component-level targeting)
componentIds requires type to be specified

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
	object (TrayFilter) Filter criteria for selecting trays in batch operations. If omitted or empty, all trays in the site are targeted. Constraints: `rackId` and `rackName` are mutually exclusive. `rackId`/`rackName` cannot be combined with `ids`/`componentIds`. `componentIds` requires `type`.
version	string Target firmware version.

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the firmware update operation

Request samples

Payload

Content type

application/json

Example

all-trays-latest

{"siteId": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Firmware update a Tray

Update firmware on a Tray identified by Tray UUID.

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
id required	string <uuid> ID of the Tray

Request Body schema: application/json
required

siteId required	string <uuid> ID of the Site
version	string Target firmware version.

Responses

Response Schema: application/json

taskIds

Array of strings <uuid> [ items <uuid > ]

List of task IDs created for the firmware update operation

Request samples

Payload

Content type

application/json

Example

with-version

{"siteId": "550e8400-e29b-41d4-a716-446655440000",
"version": "24.11.0"
}

Response samples

200
400
403

Content type

application/json

{"taskIds": ["550e8400-e29b-41d4-a716-446655440000"
]
}

Network Security Group

Network Security Group is a security policy that controls the traffic flowing between Instances.

Retrieve all Network Security Groups

Get all Network Security Groups for Tenant

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string <uuid> Filter By Site ID
status	string Filter Network Security Groups by Status
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "Tenant" "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query
includeAttachmentStats	boolean Include counts for the number objects that have attached the Network Security Group

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
status	string (NetworkSecurityGroupStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Network Security Group objects
	Array of objects (StatusDetail)
statefulEgress	boolean
	Array of objects (NetworkSecurityGroupRule)
	object (Labels) <= 10 properties
created	string <date-time>
updated	string <date-time>

Response samples

200
400
403
500
501

Content type

application/json

[{"id": "2a21cf79-ea5e-4d28-b585-2e78948fcefb",
"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"siteId": "56f1a3ed-3653-454f-b861-9136207be660",
"tenantId": "79595ebe-934f-4f19-bc74-c16aefd0c57a",
"status": "Pending",
"statusHistory": [{"status": "Ready",
"message": "processed network security group creation request",
"created": "2025-02-26T18:17:44.862879-05:00",
"updated": "2025-02-26T18:17:44.862879-05:00"
}
],
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
},
"created": "2025-02-26T18:17:44.861317-05:00",
"updated": "2025-02-26T18:17:44.861317-05:00"
}
]

Create Network Security Group

Create a Network Security Group for Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string
siteId required	string <uuid>
statefulEgress	boolean Egress rules with protocol and destination ports defined but without source ports defined should automatically be made stateful.
	Array of objects (NetworkSecurityGroupRule)
	object (Labels) <= 10 properties

Responses

Response Schema: application/json

id	string
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
status	string (NetworkSecurityGroupStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Network Security Group objects
	Array of objects (StatusDetail)
statefulEgress	boolean
	Array of objects (NetworkSecurityGroupRule)
	object (Labels) <= 10 properties
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"siteId": "188a8f32-0001-45cf-b243-f62720a22cc4",
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
}
}

Response samples

Content type

application/json

{"id": "2a21cf79-ea5e-4d28-b585-2e78948fcefb",
"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"siteId": "56f1a3ed-3653-454f-b861-9136207be660",
"tenantId": "79595ebe-934f-4f19-bc74-c16aefd0c57a",
"status": "Pending",
"statusHistory": [{"status": "Ready",
"message": "processed network security group creation request",
"created": "2025-02-26T18:17:44.862879-05:00",
"updated": "2025-02-26T18:17:44.862879-05:00"
}
],
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
},
"created": "2025-02-26T18:17:44.861317-05:00",
"updated": "2025-02-26T18:17:44.861317-05:00"
}

Retrieve Network Security Group

Get a Network Security Group by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
networkSecurityGroupId required	string ID of the Network Security Group

query Parameters

includeRelation

string

Enum: "Tenant" "Site"

Related entity to expand

Responses

Response Schema: application/json

id	string
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
status	string (NetworkSecurityGroupStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Network Security Group objects
	Array of objects (StatusDetail)
statefulEgress	boolean
	Array of objects (NetworkSecurityGroupRule)
	object (Labels) <= 10 properties
created	string <date-time>
updated	string <date-time>

Response samples

Content type

application/json

{"id": "2a21cf79-ea5e-4d28-b585-2e78948fcefb",
"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"siteId": "56f1a3ed-3653-454f-b861-9136207be660",
"tenantId": "79595ebe-934f-4f19-bc74-c16aefd0c57a",
"status": "Pending",
"statusHistory": [{"status": "Ready",
"message": "processed network security group creation request",
"created": "2025-02-26T18:17:44.862879-05:00",
"updated": "2025-02-26T18:17:44.862879-05:00"
}
],
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
},
"created": "2025-02-26T18:17:44.861317-05:00",
"updated": "2025-02-26T18:17:44.861317-05:00"
}

Update Network Security Group

Update a Network Security Group by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

After a group has been created, policy updates are absolute. The complete desired policy set must be specified.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
networkSecurityGroupId required	string ID of the Network Security Group

Request Body schema: application/json

name	string or null [ 2 .. 256 ] characters
description	string or null
statefulEgress	boolean Egress rules with protocol and destination ports defined but without source ports defined should automatically be made stateful.
	Array of objects (NetworkSecurityGroupRule) Update rules of the NetworkSecurityGroup. The rules will be entirely replaced by those sent in the request. Any rules not included in the request will be removed. To retain existing rules, first fetch them and include them.
	object (Labels) <= 10 properties

Responses

Response Schema: application/json

id	string
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
tenantId	string <uuid>
status	string (NetworkSecurityGroupStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for Network Security Group objects
	Array of objects (StatusDetail)
statefulEgress	boolean
	Array of objects (NetworkSecurityGroupRule)
	object (Labels) <= 10 properties
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
}
}

Response samples

Content type

application/json

{"id": "2a21cf79-ea5e-4d28-b585-2e78948fcefb",
"name": "Spark VPC Firewall",
"description": "Security policies for machines in Spark VPC",
"siteId": "56f1a3ed-3653-454f-b861-9136207be660",
"tenantId": "79595ebe-934f-4f19-bc74-c16aefd0c57a",
"status": "Pending",
"statusHistory": [{"status": "Ready",
"message": "processed network security group creation request",
"created": "2025-02-26T18:17:44.862879-05:00",
"updated": "2025-02-26T18:17:44.862879-05:00"
}
],
"rules": [{"name": "allow-http-from-public",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "180-181",
"protocol": "TCP",
"action": "PERMIT",
"priority": 55,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "1.1.1.1/0"
}
],
"labels": {"flavor": "coconut"
},
"created": "2025-02-26T18:17:44.861317-05:00",
"updated": "2025-02-26T18:17:44.861317-05:00"
}

Delete Network Security Group

Delete a Network Security Group by ID

Org must have a Tenant entity. Instance must belong to Tenant. User must have FORGE_TENANT_ADMIN authorization role.

Deleting a Network Security Group will also delete all the associations and all policies.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
networkSecurityGroupId required	string ID of the Network Security Group

Responses

Response samples

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

IP Block

IP Block is a contiguous block of IP addresses defined by a prefix and prefix length.

It can be used by the Provider to describe the overlay network of a particular Site. Providers can also use Allocations to delegate portions of these IP Blocks to Tenants.

Deprecation history:

blockSize was deprecated in favor of prefixLength and was removed on April 15th, 2023 0:00 UTC. Please use prefixLength instead.

Retrieve all IP Blocks

Retrieve all IP blocks for the org.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role. infrastructureProviderId or tenantId query param may be required for older API versions.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

infrastructureProviderId	string <uuid> Filter IP Blocks by Infrastructure Provider ID
tenantId	string <uuid> Filter IP Blocks by Tenant ID
siteId	string <uuid> Filter IP Blocks by Site ID
status	string Filter IP Blocks by Status
includeUsageStats	boolean Include IP Block usage stats in response
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "PREFIX_ASC" "PREFIX_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
infrastructureProviderId	string <uuid>
tenantId	string or null <uuid>
routingType	string Enum: "Public" "DatacenterOnly"
prefix	string Either IPv4 or IPv6 address
prefixLength	integer Min: 1, Max: 32 for ipv4, 128 for ipv6
protocolVersion	string Enum: "IPv4" "IPv6"
	object (IpBlockUsageStats) Usa statistics for an IP Block
status	string (IpBlockStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for IP Block objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Public Network Overlay for Site SJC4",
"description": "This is the primary IP overlay for SJC4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": null,
"routingType": "Public",
"prefix": "202.168.1.0",
"prefixLength": 24,
"protocolVersion": "IPv4",
"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"
}
]

Create IP Block

Create an IP block for the org.

Only Infrastructure Providers can create a root IP Block. User must have FORGE_PROVIDER_ADMIN role.

Tenant IP Blocks are created via Allocation.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string [ 2 .. 256 ] characters
description	string
siteId required	string <uuid>
routingType required	string Enum: "Public" "DatacenterOnly"
prefix required	string Either IPv4 or IPv6 address
prefixLength required	integer Min: 1, Max: 32 for IPv4, 128 for IPv6
protocolVersion required	string Enum: "IPv4" "IPv6"

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
infrastructureProviderId	string <uuid>
tenantId	string or null <uuid>
routingType	string Enum: "Public" "DatacenterOnly"
prefix	string Either IPv4 or IPv6 address
prefixLength	integer Min: 1, Max: 32 for ipv4, 128 for ipv6
protocolVersion	string Enum: "IPv4" "IPv6"
	object (IpBlockUsageStats) Usa statistics for an IP Block
status	string (IpBlockStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for IP Block objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "Public Network Overlay for Site SJC4",
"description": "This is the primary IP overlay for SJC4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"routingType": "Public",
"prefix": "202.168.1.0",
"prefixLength": 24,
"protocolVersion": "IPv4"
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Public Network Overlay for Site SJC4",
"description": "This is the primary IP overlay for SJC4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": null,
"routingType": "Public",
"prefix": "202.168.1.0",
"prefixLength": 24,
"protocolVersion": "IPv4",
"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"
}

Retrieve IP Block

Retrieve an IP Block by ID.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
ipBlockId required	string ID of the IP Block

query Parameters

infrastructureProviderId	string <uuid> Filter IP Blocks by Infrastructure Provider ID
tenantId	string <uuid> Filter IP Blocks by Tenant ID
includeUsageStats	boolean Include IP Block usage stats in response
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" Related entity to expand

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
infrastructureProviderId	string <uuid>
tenantId	string or null <uuid>
routingType	string Enum: "Public" "DatacenterOnly"
prefix	string Either IPv4 or IPv6 address
prefixLength	integer Min: 1, Max: 32 for ipv4, 128 for ipv6
protocolVersion	string Enum: "IPv4" "IPv6"
	object (IpBlockUsageStats) Usa statistics for an IP Block
status	string (IpBlockStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for IP Block objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Public Network Overlay for Site SJC4",
"description": "This is the primary IP overlay for SJC4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": null,
"routingType": "Public",
"prefix": "202.168.16.0",
"prefixLength": 20,
"protocolVersion": "IPv4",
"usageStats": {"availableIPs": 256,
"acquiredIPs": 2,
"availablePrefixes": ["192.168.201.0/24"
],
"availableSmallestPrefixes": 64,
"acquiredPrefixes": 0
},
"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"
}

Delete IP Block

Delete an IP block

Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role. Only root IP Blocks can be deleted if there are no allocations associated with it.

Tenant IP Blocks are managed via Allocation.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
ipBlockId required	string ID of the IP Block

Responses

Response samples

400
403

Content type

application/json

{"source": "carbide",
"message": "Error validating request data",
"data": {"name": "A value is required"
}
}

Update IP Block

Update an existing IP Block

Org must have an Infrastructure Provider. Specified IP Block must have been created by the Provider and requesting user must have FORGE_PROVIDER_ADMIN role. Only root IP Blocks can be patched.

Tenant IP Blocks are managed via Allocation.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
ipBlockId required	string ID of the IP Block

Request Body schema: application/json

name	string [ 2 .. 256 ] characters
description	string

Responses

Response Schema: application/json

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
infrastructureProviderId	string <uuid>
tenantId	string or null <uuid>
routingType	string Enum: "Public" "DatacenterOnly"
prefix	string Either IPv4 or IPv6 address
prefixLength	integer Min: 1, Max: 32 for ipv4, 128 for ipv6
protocolVersion	string Enum: "IPv4" "IPv6"
	object (IpBlockUsageStats) Usa statistics for an IP Block
status	string (IpBlockStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for IP Block objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Request samples

Payload

Content type

application/json

{"name": "Public Network Overlay for Site SJC-4",
"description": "This is the primary IP overlay for SJC-4. All IPs are publicly routable"
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Public Network Overlay for Site SJC-4",
"description": "This is the primary IP overlay for SJC-4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": null,
"routingType": "Public",
"prefix": "202.168.16.0",
"prefixLength": 20,
"protocolVersion": "IPv4",
"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"
}

Retrieve All Derived IP Blocks

Retrieve all child IP Blocks allocated to Tenants from a specific Provider super IP Block. When allocations are created from a super block, individual Tenant IP Blocks are created as a result.

The IP Block in URL must belong to the Infrastructure Provider associated with the Org.

User must have FORGE_PROVIDER_ADMIN role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
ipBlockId required	string ID of the IP Block

query Parameters

status	string Filter IP Blocks by Status
query	string Search for matches across all Sites. Input will be matched against name, description and status fields
includeRelation	string Enum: "InfrastructureProvider" "Tenant" "Site" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "PREFIX_ASC" "PREFIX_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid>
name	string [ 2 .. 256 ] characters
description	string
siteId	string <uuid>
infrastructureProviderId	string <uuid>
tenantId	string or null <uuid>
routingType	string Enum: "Public" "DatacenterOnly"
prefix	string Either IPv4 or IPv6 address
prefixLength	integer Min: 1, Max: 32 for ipv4, 128 for ipv6
protocolVersion	string Enum: "IPv4" "IPv6"
	object (IpBlockUsageStats) Usa statistics for an IP Block
status	string (IpBlockStatus) Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error" Status values for IP Block objects
	Array of objects (StatusDetail)
	Array of objects (Deprecation)
created	string <date-time>
updated	string <date-time>

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Public Network Overlay for Site SJC4",
"description": "This is the primary IP overlay for SJC4. All IPs are publicly routable",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
"tenantId": "97c57510-b443-43b4-881c-974d4b86c87c",
"routingType": "Public",
"prefix": "202.168.1.0",
"prefixLength": 24,
"protocolVersion": "IPv4",
"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"
}
]

DPU Extension Service

DPU Extension Service allows users to run custom services in the DPUs of their Instances. Currently K8s pods are the only supported service type.

Retrieve all DPU Extension Services

Retrieve all DPU Extension Services for the current Tenant

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string Filter DPU Extension Services by Site ID
status	string Enum: "Pending" "Ready" "Error" "Deleting" Status filter for the DPU Extension Services
query	string Search for matches across all Sites. Input will be matched against name, description and status
includeRelation	string Enum: "Site" "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Headers
X-Pagination	string Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}" Pagination result in JSON format

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the DPU Extension Service
name	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string or null Optional description for the DPU Extension Service
serviceType	string Value: "KubernetesPod" Type of the DPU Extension Service
siteId	string <uuid> ID for the Site the DPU Extension Service belongs to
tenantId	string <uuid> ID for the Tenant the DPU Extension Service belongs to
version	string or null Latest version of the DPU Extension Service
	object (DpuExtensionServiceVersionInfo) Details for the latest version of the DPU Extension Service
activeVersions	Array of strings Latest and past versions of this DPU Extension Service that have not been deleted and are available for deployment
status	string (DpuExtensionServiceStatus) Enum: "Pending" "Ready" "Error" "Deleting" Status of the DPU Extension Service
	Array of objects (StatusDetail) History of the DPU Extension Service statuses
created	string <date-time> Date/time when the DPU Extension Service was created
updated	string <date-time> Date/time when the DPU Extension Service was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"description": "Single, multi-call executable that contains stripped-down versions of common Unix utilities",
"serviceType": "KubernetesPod",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "V1-T1761856992374052",
"versionInfo": {"version": "V1-T1761856992374052",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"hasCredentials": true,
"created": "2019-08-24T14:15:22Z",
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
},
"activeVersions": ["V1-T1761857134382532",
"V1-T1761856992374052"
],
"status": "Ready",
"statusHistory": [{"status": "Pending",
"message": "DPU Service Extension is ready for use",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"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"
}
]

Create DPU Extension Service

Create a DPU Extension Service for the current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string or null Optional description for the DPU Extension Service
serviceType required	string Value: "KubernetesPod" Type of the DPU Extension Service
siteId required	string <uuid> ID for the Site the DPU Extension Service belongs to
data required	string Deployment spec for the DPU Extension Service
	object (DpuExtensionServiceCredentials) Credentials to download resources specified in DPU Extension Service data
	object (DpuExtensionServiceObservability) Observability configuration for the DPU Extension Service version

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the DPU Extension Service
name	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string or null Optional description for the DPU Extension Service
serviceType	string Value: "KubernetesPod" Type of the DPU Extension Service
siteId	string <uuid> ID for the Site the DPU Extension Service belongs to
tenantId	string <uuid> ID for the Tenant the DPU Extension Service belongs to
version	string or null Latest version of the DPU Extension Service
	object (DpuExtensionServiceVersionInfo) Details for the latest version of the DPU Extension Service
activeVersions	Array of strings Latest and past versions of this DPU Extension Service that have not been deleted and are available for deployment
status	string (DpuExtensionServiceStatus) Enum: "Pending" "Ready" "Error" "Deleting" Status of the DPU Extension Service
	Array of objects (StatusDetail) History of the DPU Extension Service statuses
created	string <date-time> Date/time when the DPU Extension Service was created
updated	string <date-time> Date/time when the DPU Extension Service was last updated

Request samples

Payload

Content type

application/json

{"name": "busybox",
"description": "Single, multi-call executable that contains stripped-down versions of common Unix utilities",
"serviceType": "KubernetesPod",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"credentials": {"registryUrl": "https://registry.hub.docker.com",
"username": "johndoe",
"password": "password123"
},
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"description": "Single, multi-call executable that contains stripped-down versions of common Unix utilities",
"serviceType": "KubernetesPod",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "V1-T1761856992374052",
"versionInfo": {"version": "V1-T1761856992374052",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"hasCredentials": true,
"created": "2019-08-24T14:15:22Z",
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
},
"activeVersions": ["V1-T1761857134382532",
"V1-T1761856992374052"
],
"status": "Ready",
"statusHistory": [{"status": "Pending",
"message": "DPU Service Extension is ready for use",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"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"
}

Retrieve DPU Extension Service

Retrieve a DPU Extension Service for the current Tenant by ID

DPU Extension Service must be owned by current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
dpuExtensionServiceId required	string ID of the DPU Extension Service

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the DPU Extension Service
name	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string or null Optional description for the DPU Extension Service
serviceType	string Value: "KubernetesPod" Type of the DPU Extension Service
siteId	string <uuid> ID for the Site the DPU Extension Service belongs to
tenantId	string <uuid> ID for the Tenant the DPU Extension Service belongs to
version	string or null Latest version of the DPU Extension Service
	object (DpuExtensionServiceVersionInfo) Details for the latest version of the DPU Extension Service
activeVersions	Array of strings Latest and past versions of this DPU Extension Service that have not been deleted and are available for deployment
status	string (DpuExtensionServiceStatus) Enum: "Pending" "Ready" "Error" "Deleting" Status of the DPU Extension Service
	Array of objects (StatusDetail) History of the DPU Extension Service statuses
created	string <date-time> Date/time when the DPU Extension Service was created
updated	string <date-time> Date/time when the DPU Extension Service was last updated

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"description": "Single, multi-call executable that contains stripped-down versions of common Unix utilities",
"serviceType": "KubernetesPod",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "V1-T1761856992374052",
"versionInfo": {"version": "V1-T1761856992374052",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"hasCredentials": true,
"created": "2019-08-24T14:15:22Z",
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
},
"activeVersions": ["V1-T1761857134382532",
"V1-T1761856992374052"
],
"status": "Ready",
"statusHistory": [{"status": "Pending",
"message": "DPU Service Extension is ready for use",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"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"
}

Delete DPU Extension Service

Delete a specific DPU Extension Service by ID. All versions will be deleted.

DPU Extension Service must be owned by current Tenant. No versions of the DPU Extension Service can have active deployments.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
dpuExtensionServiceId required	string ID of the DPU Extension Service

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update DPU Extension Service

Update a specific DPU Extension Service.

DPU Extension Service must be owned by current Tenant. A new version will be created if data or credentials are modified.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
dpuExtensionServiceId required	string ID of the DPU Extension Service

Request Body schema: application/json

name	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string Optional description for the DPU Extension Service
data	string Deployment spec for the DPU Extension Service
	object (DpuExtensionServiceCredentials) Credentials to download resources specified in DPU Extension Service data
	object (DpuExtensionServiceObservability) Observability configuration for the DPU Extension Service version

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the DPU Extension Service
name	string Name for the DPU Extension Service. Must be unique for a given Tenant
description	string or null Optional description for the DPU Extension Service
serviceType	string Value: "KubernetesPod" Type of the DPU Extension Service
siteId	string <uuid> ID for the Site the DPU Extension Service belongs to
tenantId	string <uuid> ID for the Tenant the DPU Extension Service belongs to
version	string or null Latest version of the DPU Extension Service
	object (DpuExtensionServiceVersionInfo) Details for the latest version of the DPU Extension Service
activeVersions	Array of strings Latest and past versions of this DPU Extension Service that have not been deleted and are available for deployment
status	string (DpuExtensionServiceStatus) Enum: "Pending" "Ready" "Error" "Deleting" Status of the DPU Extension Service
	Array of objects (StatusDetail) History of the DPU Extension Service statuses
created	string <date-time> Date/time when the DPU Extension Service was created
updated	string <date-time> Date/time when the DPU Extension Service was last updated

Request samples

Payload

Content type

application/json

{"name": "busybox-ha",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 3 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"credentials": {"registryUrl": "https://registry.hub.docker.com",
"username": "johndoe",
"password": "password123"
},
"observability": {"configs": [{"name": "busybox-logs",
"logging": {"path": "/var/log/busybox.log"
}
}
]
}
}

Response samples

200
400
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "busybox",
"description": "Single, multi-call executable that contains stripped-down versions of common Unix utilities",
"serviceType": "KubernetesPod",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "V1-T1761856992374052",
"versionInfo": {"version": "V1-T1761856992374052",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"hasCredentials": true,
"created": "2019-08-24T14:15:22Z",
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
},
"activeVersions": ["V1-T1761857134382532",
"V1-T1761856992374052"
],
"status": "Ready",
"statusHistory": [{"status": "Pending",
"message": "DPU Service Extension is ready for use",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"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"
}

Retrieve DPU Extension Service Version

Retrieve details for a specific version of a DPU Extension Service.

DPU Extension Service must be owned by current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
dpuExtensionServiceId required	string ID of the DPU Extension Service
version required	string Version of the DPU Extension Service

Responses

Response Schema: application/json

version	string or null Current version of the DPU Extension Service
data	string Deployment spec for the DPU Extension Service
hasCredentials	boolean Indicates whether this version was created with credentials
created	string <date-time> Date/time when this version of the DPU Extension Service was created
	object (DpuExtensionServiceObservability) Observability configuration for this DPU Extension Service version

Response samples

200
403
404

Content type

application/json

{"version": "V1-T1761856992374052",
"data": "apiVersion: apps/v1\\nkind: Deployment\\nmetadata:\\n  name: busybox-deployment\\n  labels:\\n    app: busybox\\nspec:\\n  replicas: 1 # You can adjust the number of desired replicas here\\n  selector:\\n    matchLabels:\\n      app: busybox\\n  template:\\n    metadata:\\n      labels:\\n        app: busybox\\n    spec:\\n      containers:\\n      - name: busybox-container\\n        image: busybox:latest # You can specify a different BusyBox image tag\\n        command: [\"sh\", \"-c\", \"echo \\'BusyBox container running\\' && sleep 3600\"]",
"hasCredentials": true,
"created": "2019-08-24T14:15:22Z",
"observability": {"configs": [{"name": "busybox-metrics",
"prometheus": {"scrapeIntervalSeconds": 30,
"endpoint": "busybox:9090"
}
}
]
}
}

Delete DPU Extension Service Version

Delete a specific version of a DPU Extension Service.

DPU Extension Service must be owned by current Tenant. The version being deleted cannot have active deployments.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
dpuExtensionServiceId required	string ID of the DPU Extension Service
version required	string Version of the DPU Extension Service

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

SSH Key Group

SSH Key Groups allow grouping several SSH Keys together so they can be synced to Sites and used to access the Serial Console of Instances.

Retrieve all SSH Key Groups

Retrieve all SSH Key Groups for the current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

siteId	string Filter SSH Key Groups by Site ID
instanceId	string Filter SSH Key Groups by Instance ID
status	string Enum: "Syncing" "Synced" "Error" "Deleting" Status filter for the SSH Key Groups
query	string Search for matches across all Sites. Input will be matched against name field
includeRelation	string Value: "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the SSH Key Group
name	string Name of the SSH Key Group
description	string or null Description for the SSH Key Group, optional
org	string Organization this SSH Key Group belongs to
tenantId	string <uuid> ID of the Tenane the SSH Key Group belongs to
version	string Version of the SSH Key Group
	Array of objects (SshKey) SSH Keys associated with this SSH Key Group
	Array of objects (SshKeyGroupSiteAssociation) Sites the SSH Key Group is synced to
status	string (SshKeyGroupStatus) Enum: "Syncing" "Synced" "Error" "Deleting" Status of the SSH Key Group
	Array of objects (StatusDetail) History of the SSH Key Group states
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"siteAssociations": [{"site": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": false,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeys": [{"id": "ff06da79-707a-4069-8623-211d49ae96c8",
"name": "sre-ssh-reno",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "Group is being synced to Sites",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create SSH Key Group

Create an SSH Key Group for the current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string
description	string
siteIds	Array of strings <uuid> [ items <uuid > ]
sshKeyIds	Array of strings <uuid> [ items <uuid > ]

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the SSH Key Group
name	string Name of the SSH Key Group
description	string or null Description for the SSH Key Group, optional
org	string Organization this SSH Key Group belongs to
tenantId	string <uuid> ID of the Tenane the SSH Key Group belongs to
version	string Version of the SSH Key Group
	Array of objects (SshKey) SSH Keys associated with this SSH Key Group
	Array of objects (SshKeyGroupSiteAssociation) Sites the SSH Key Group is synced to
status	string (SshKeyGroupStatus) Enum: "Syncing" "Synced" "Error" "Deleting" Status of the SSH Key Group
	Array of objects (StatusDetail) History of the SSH Key Group states
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Request samples

Payload

Content type

application/json

{"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"siteIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"sshKeyIds": ["ff06da79-707a-4069-8623-211d49ae96c8"
]
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"siteAssociations": [{"site": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeys": [{"id": "ff06da79-707a-4069-8623-211d49ae96c8",
"name": "sre-ssh-reno",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "Group is being synced to Sites",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve an SSH Key Group

Retrieve an SSH Key Group for the current Tenant by ID

SSH Key Group must be owned by current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyGroupId required	string ID of the SSH Key Group

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the SSH Key Group
name	string Name of the SSH Key Group
description	string or null Description for the SSH Key Group, optional
org	string Organization this SSH Key Group belongs to
tenantId	string <uuid> ID of the Tenane the SSH Key Group belongs to
version	string Version of the SSH Key Group
	Array of objects (SshKey) SSH Keys associated with this SSH Key Group
	Array of objects (SshKeyGroupSiteAssociation) Sites the SSH Key Group is synced to
status	string (SshKeyGroupStatus) Enum: "Syncing" "Synced" "Error" "Deleting" Status of the SSH Key Group
	Array of objects (StatusDetail) History of the SSH Key Group states
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-integration-sre",
"description": "SRE access SSH keys for Reno Integration",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"siteAssociations": [{"site": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true,
"nvLinkPartition": false,
"rackLevelAdministration": false,
"imageBasedOperatingSystem": false
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeys": [{"id": "ff06da79-707a-4069-8623-211d49ae96c8",
"name": "sre-ssh-reno",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "Group is being synced to Sites",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete an SSH Key Group

Delete a specific SSH key Group.

SSH Key Group must be owned by current Tenant. All Sites associated must be online to proceed.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyGroupId required	string ID of the SSH Key Group

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update an SSH Key Group

Update a specific SSH Key Group.

SSH Key Group must be owned by current Tenant. All Sites being added or removed must be online to proceed.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyGroupId required	string ID of the SSH Key Group

Request Body schema: application/json

name	string or null
description	string or null
siteIds	Array of strings <uuid> [ items <uuid > ] When specified, replaces existing Site associations
sshKeyIds	Array of strings <uuid> [ items <uuid > ] When specified, replaces existing SSH Key associations
version required	string Version of the SSH Key Group being modified must be provided

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the SSH Key Group
name	string Name of the SSH Key Group
description	string or null Description for the SSH Key Group, optional
org	string Organization this SSH Key Group belongs to
tenantId	string <uuid> ID of the Tenane the SSH Key Group belongs to
version	string Version of the SSH Key Group
	Array of objects (SshKey) SSH Keys associated with this SSH Key Group
	Array of objects (SshKeyGroupSiteAssociation) Sites the SSH Key Group is synced to
status	string (SshKeyGroupStatus) Enum: "Syncing" "Synced" "Error" "Deleting" Status of the SSH Key Group
	Array of objects (StatusDetail) History of the SSH Key Group states
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Request samples

Payload

Content type

application/json

{"name": "reno-int-sre",
"description": "SRE access SSH keys for Reno Integration Site",
"siteIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08",
"05d6e108-9f06-44c9-be47-7ab4d62b20d0"
],
"sshKeyIds": ["ff06da79-707a-4069-8623-211d49ae96c8",
"30fc7238-133d-42f7-8d29-866658b0c019"
],
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75"
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-int-sre",
"description": "SRE access SSH keys for Reno Integration Site",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
"siteAssociations": [{"site": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "sjc-central-1",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"site": {"id": "05d6e108-9f06-44c9-be47-7ab4d62b20d0",
"name": "Reno Integration",
"infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
"isSerialConsoleEnabled": true,
"isOnline": true,
"capabilities": {"nativeNetworking": true,
"networkSecurityGroup": true
},
"status": "Registered"
},
"status": "Syncing",
"version": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"sshKeys": [{"id": "ff06da79-707a-4069-8623-211d49ae96c8",
"name": "sre-ssh-reno",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
},
{"id": "30fc7238-133d-42f7-8d29-866658b0c019",
"name": "sre-ssh-reno-ext",
"org": "wdksahew1rqf",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"status": "Syncing",
"statusHistory": [{"status": "Syncing",
"message": "Group is being synced to Sites",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

SSH Key

SSH Key is a public key that can be used to access the Serial Console of an Instance.

Retrieve all SSH Keys

Retrieve all SSH Keys for the current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

sshKeyGroupId	string ID of the SSH Key Group
query	string Search for matches across all Sites. Input will be matched against name field
includeRelation	string Value: "Tenant" Related entity to expand
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" Ordering for pagination query

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier for the key
name	string
org	string
tenantId	string <uuid>
fingerprint	string SHA256 fingerprint of the public key
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Response samples

200
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "staging-sre-access",
"org": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]

Create SSH Key

Create an SSH Key for the current Tenant. If an SSH Key Group is specified, all Sites associated with the SSH Key Group must be online.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Request Body schema: application/json

name required	string Name cannot match that name an existing SSH Key
publicKey required	string^ssh-(rsa\|ecdsa\|ed25519) AAAA[0-9A-Za-z+/]+[=... Must be an SSH key of type: RSA, ECDSA or ED25519
sshKeyGroupId	string or null <uuid> ID of the SSH Key Group this key should be attached to

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the key
name	string
org	string
tenantId	string <uuid>
fingerprint	string SHA256 fingerprint of the public key
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Request samples

Payload

Content type

application/json

{"name": "reno-sre-access",
"publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICip4hl6WjuVHs60PeikVUs0sWE/kPhk2D0rRHWsIuyL jdoe@test.com",
"sshKeyGroupId": "86ca8cab-b285-4c2d-9e00-25c88810dc2e"
}

Response samples

201
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-sre-access",
"org": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Retrieve an SSH key

Retrieve an SSH key for the current Tenant by ID

SSH Key must be owned by current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyId required	string ID of the SSH Key

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the key
name	string
org	string
tenantId	string <uuid>
fingerprint	string SHA256 fingerprint of the public key
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Response samples

200
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "staging-sre-access",
"org": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Delete an SSH Key

Delete an SSH key for the current Tenant by ID.

SSH Key must be owned by current Tenant. All Site associated with the SSH Key Groups this SSH Key is part of must be online to proceed.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyId required	string ID of the SSH Key

Responses

Response samples

403

Content type

application/json

{"source": "carbide",
"message": "User is not allowed to perform this action",
"data": null
}

Update an SSH Key

Update an SSH Key for the current Tenant by ID.

SSH Key must be owned by current Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

To add this SSH Key to various SSH Key Groups or remove it from an SSH Key Group, please use SSH Key Group update endpoint.

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
sshKeyId required	string ID of the SSH Key

Request Body schema: application/json

name

string

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the key
name	string
org	string
tenantId	string <uuid>
fingerprint	string SHA256 fingerprint of the public key
created	string <date-time> Date/time when the SSH key was created
updated	string <date-time> Date/time when the SSH key was last updated

Request samples

Payload

Content type

application/json

{"name": "reno-sre-access-v2"
}

Response samples

200
400
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "reno-sre-access-v2",
"org": "xskkpgqpeakn",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"fingerprint": "CaK2yoj5fDOhf1swM2kFyjQrd3bwZfDYlWnVjBHgveQ",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

User

User is a logical entity that identifies individuals operating on behalf of an organization.

Retrieve Current User

Retrieve details of the current user.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

id	string <uuid> Unique identifier for the given user.
email	string <email>
firstName	string
lastName	string
created	string <date-time> The date that the user was created.
updated	string <date-time>

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "janed@nvidia.com",
"firstName": "Jane",
"lastName": "Doe",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}

Audit

Audit is a record of actions taken by users on the API.

Retrieve all Audit Log Entries

Get all Audit Log entries

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN authorization role.

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

query Parameters

failedOnly	boolean Return only audit log entries that have failed status code (>= 400)
pageNumber	integer >= 1 Default: 1 Example: pageNumber=1 Page number for pagination query
pageSize	integer [ 1 .. 100 ] Example: pageSize=20 Page size for pagination query
orderBy	string Enum: "TIMESTAMP_ASC" "TIMESTAMP_DESC" Ordering for pagination query

Responses

Response Schema: application/json

Array

id	string <uuid> Unique identifier
endpoint	string API endpoint
queryParams	string Query parameters
method	string HTTP method
body	string HTTP body in JSON format
statusCode	integer HTTP response status code
statusMessage	string HTTP response status message
clientIP	string Client IP address
userID	string or null <uuid> User ID that executed the API call
	object (User) User that executed the API call
orgName	string Organization name
extraData	object Extra data in JSON format
timestamp	string <date-time> API execution time
durationMs	integer API execution duration in milliseconds
apiVersion	string API version

Response samples

200
403

Content type

application/json

[{"id": "e313b3ca-c47a-4ec1-a79b-a147fad51a50",
"endpoint": "/v2/org/test-org-1/carbide/ep",
"queryParams": "{\"test\":[\"1234\"]}",
"method": "POST",
"body": "{\"key1\":\"value1\"}",
"statusCode": 200,
"clientIP": "12.123.43.112",
"userID": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"user": {"id": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@test.com"
},
"orgName": "test-org-1",
"timestamp": "2024-12-04T21:06:33.849293-08:00",
"durationMs": 250,
"apiVersion": "0.1.91"
},
{"id": "e313b3ca-c47a-4ec1-a79b-a147fad51a50",
"endpoint": "/v2/org/test-org-1/carbide/ep",
"queryParams": "{\"test\":[\"1234\"]}",
"method": "POST",
"body": "{\"key1\":\"value1\"}",
"statusCode": 403,
"statusMessage": "User does not have permissions",
"clientIP": "12.123.43.112",
"userID": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"user": {"id": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@test.com"
},
"orgName": "test-org-1",
"timestamp": "2024-12-04T21:06:33.849293-08:00",
"durationMs": 50,
"apiVersion": "0.1.91"
}
]

Retrieve Audit Log Entry

Retrieve a specific Audit Log Entry by ID

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN authorization role

Authorizations:

JWTBearerToken

path Parameters

org required	string Name of the Org
auditEntryId required	string ID of the Audit Log Entry

Responses

Response Schema: application/json

id	string <uuid> Unique identifier
endpoint	string API endpoint
queryParams	string Query parameters
method	string HTTP method
body	string HTTP body in JSON format
statusCode	integer HTTP response status code
statusMessage	string HTTP response status message
clientIP	string Client IP address
userID	string or null <uuid> User ID that executed the API call
	object (User) User that executed the API call
orgName	string Organization name
extraData	object Extra data in JSON format
timestamp	string <date-time> API execution time
durationMs	integer API execution duration in milliseconds
apiVersion	string API version

Response samples

200
403

Content type

application/json

{"id": "e313b3ca-c47a-4ec1-a79b-a147fad51a50",
"endpoint": "/v2/org/test-org-1/carbide/ep",
"queryParams": "{\"test\":[\"1234\"]}",
"method": "POST",
"body": "{\"key1\":\"value1\"}",
"statusCode": 200,
"clientIP": "12.123.43.112",
"userID": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"user": {"id": "5d9fe319-14d4-40e3-8e5a-7d79e680d55b",
"firstName": "John",
"lastName": "Doe",
"email": "jdoe@test.com"
},
"orgName": "test-org-1",
"timestamp": "2024-12-04T21:06:33.849293-08:00",
"durationMs": 250,
"apiVersion": "0.1.91"
}

Metadata

Metadata describes various system level attributes of the API service.

Retrieve metadata about the API server

Retrieve system metadata providing information about the API server

Authorizations:

JWTBearerToken

path Parameters

org

required

string

Name of the Org

Responses

Response Schema: application/json

version	string Current version of the API
buildTime	string Date/time when the API was built

Response samples

200

Content type

application/json

{"version": "0.1.24",
"buildTime": "2019-08-24T14:15:22Z"
}

Deprecations

NICo REST API maintains backward compatibility with the previous versions. Any breaking changes are announced using deprecation notices.

Endpoints that have deprecations will be grouped here. Following deprecations are in effect or slated to be effective in future:

Infrastructure Provider:

name attribute was deprecated and was removed on August 17th, 2023 0:00 UTC. Please use orgDisplayName instead.
POST /org/:orgName/carbide/infrastructure-provider endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Providers are automatically created when retrieved by a Provider Admin.
PATCH /org/:orgName/carbide/infrastructure-provider/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Provider details are populated from Org information and cannot be updated by user.

Tenant:

name attribute was deprecated and was removed on August 17th, 2023. Please use orgDisplayName instead.
enableSSHAccess attribute was deprecated and was removed on August 17th, 2023 0:00 UTC. Please use 'isSerialConsoleSSHKeysEnabled' attribute of Site instead.
POST /org/:orgName/carbide/tenant endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenants are automatically created when retrieved by a Tenant Admin.
PATCH /org/:orgName/carbide/tenant/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenant details are populated from Org information and cannot be updated by user.

Instance Type:

includeMachineAssociation was deprecated in favor of includeMachineAssignment and was removed on July 26th, 2023 0:00 UTC. Please use includeMachineAssignment instead.
displayName attribute was deprecated and removed on October 30, 2024 0:00 UTC. Please update your usage accordingly.

Instance:

sshUrl was deprecated in favor of serialConsoleUrl and was removed on April 25th, 2023 0:00 UTC. Please use serialConsoleUrl instead.
instanceSubnets was deprecated in favor of interfaces and was removed on May 10th, 2023 0:00 UTC. Please use interfaces instead.
sshkeygroups was deprecated in favor of sshKeyGroups and was removed on September 4th, 2025 0:00 UTC. Please use sshKeyGroups instead.

IP Block:

blockSize was deprecated in favor of prefixLength and was removed on April 15th, 2023 0:00 UTC. Please use prefixLength instead.

Subnet:

ipBlockSize was deprecated in favor of prefixLength and was removed on April 15th, 2023 0:00 UTC. Please use prefixLength instead.