API docs by Redocly

NVIDIA Bare Metal Manager REST API (1.0.4)

Download OpenAPI specification:

NVIDIA Bare Metal Manager Dev Team: carbide-dev@exchange.nvidia.com License: Apache-2.0

NVIDIA Bare Metal Manager REST API is the centralized RESTful gateway to access NVIDIA Bare Metal Manager service

NVIDIA Bare Metal Manager REST API allows users to create and manage resources e.g. VPC, Subnets, Instances across all connected NVIDIA Bare Metal Manager datacenters, also referred to as Sites.

Service Account

When API service is configured in Service Account mode, API users can act as both Provider and Tenant

Retrieve Service Account status for current org

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 samples

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

Infrastructure Provider

Infrastructure Provider issues a unique identifier for a Provider and contains information about their Org

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 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 samples

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 samples

Content type
application/json
{
  • "machine": {
    },
  • "ipBlock": {
    },
  • "tenantAccount": {
    }
}

Tenant

Tenant issues a unique identifier for a Tenant and contains information about their Org

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 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 samples

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": {
    }
}

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 samples

Content type
application/json
{
  • "instance": {
    },
  • "vpc": {
    },
  • "subnet": {
    }
}

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

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 samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
  • "tenantOrg": "rf43bbtnb9c5"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
  • "infrastructureProviderOrg": "xskkpgqpeakn",
  • "tenantId": null,
  • "tenantOrg": "rf43bbtnb9c5",
  • "tenantContact": {
    },
  • "allocationCount": 0,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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 samples

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": {
    },
  • "allocationCount": 2,
  • "status": "Ready",
  • "statusHistory": [
    ],
  • "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

Request samples

Content type
application/json
{ }

Response samples

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": {
    },
  • "allocationCount": 0,
  • "status": "Ready",
  • "statusHistory": [
    ],
  • "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

Content type
application/json
{
  • "source": "carbide",
  • "message": "User is not allowed to perform this action",
  • "data": null
}

Site

Site operations

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.

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 samples

Content type
application/json
[
  • {
    }
]

Create Site

Create a Site for the org.

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

Tenant cannot create a Site.

Authorizations:
JWTBearerToken
path Parameters
org
required
string

Name of the Org

Request Body schema: application/json
name
required
string [ 2 .. 256 ] characters
description
string
serialConsoleHostname
string <hostname>

Hostname to reach Serial Console for the Site

object (SiteLocation)

Location of the Site

object (SiteContact)

Contact for the Site

Responses

Request samples

Content type
application/json
{
  • "name": "San Jose Central 4",
  • "description": "Datacenter serving San Jose central region",
  • "location": {
    },
  • "contact": {
    }
}

Response samples

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": {
    },
  • "capabilities": {
    },
  • "isOnline": false,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "location": {
    },
  • "contact": {
    }
}

Retrieve Site

Retrieve a specific Site by ID.

User must have FORGE_PROVIDER_ADMIN or FORGE_TENANT_ADMIN role.

Authorizations:
JWTBearerToken
path Parameters
org
required
string

Name of the Org

siteId
required
string <uuid>

ID of the Site

Responses

Response samples

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": {
    },
  • "capabilities": {
    },
  • "isOnline": false,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "location": {
    },
  • "contact": {
    }
}

Update Site

Update a specific Site

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

Infrastructure Provider updating the Site must be the owner of the Site.

Tenant updating the Site must have access to the Site and can only update Tenant specific attributes.

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

Enable/disable Serial Console. Can only be updated by Provider

serialConsoleIdleTimeout
integer

Maximum idle time in seconds before Serial Console is disconnected. Can only be updated by Provider

serialConsoleMaxSessionLength
integer

Maximum length of Serial Console session in seconds. Can only be updated by Provider

isSerialConsoleSSHKeysEnabled
boolean

Enable/disable Serial Console access using SSH Keys. Can only be updated by Tenant

object (SiteLocation)

Location of the Site

object (SiteContact)

Contact for the Site

Responses

Request samples

Content type
application/json
Example
{
  • "name": "San Jose Central No.4",
  • "description": "Datacenter 4 serving central San Jose",
  • "renewRegistrationToken": true,
  • "serialConsoleHostname": "sol.carbide.acme.com",
  • "isSerialConsoleEnabled": true,
  • "serialConsoleIdleTimeout": 120,
  • "serialConsoleMaxSessionLength": 1800,
  • "location": {
    },
  • "contact": {
    }
}

Response samples

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": {
    },
  • "capabilities": {
    },
  • "isOnline": false,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "location": {
    },
  • "contact": {
    }
}

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

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. The Infrastructure Provider must own the Site.

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. The Tenant must have an allocation with the Site.

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 samples

Content type
application/json
[
  • {
    }
]

Allocation

Allocation operations

Retrieve all Allocations

Retrieve all Allocations for the org.

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 Allocations by Infrastructure Provider ID

tenantId
string <uuid>

Filter Allocations by Tenant ID. Can be specified multiple times to filter on more than one 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 samples

Content type
application/json
[
  • {
    }
]

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
description
string
tenantId
required
string <uuid>
siteId
required
string <uuid>
Array of objects (AllocationConstraintCreateRequest)

Responses

Request samples

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": [
    ]
}

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "allocationConstraints": [
    ]
}

Retrieve Allocation

Retrieve Allocation by ID

Allocation must belong either to the Provider associated with the org or the Tenant associated with the org.

User must have FORGE_PROVIDER_ADMIN, 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>

Filter Allocations by Infrastructure Provider ID

tenantId
string <uuid>

Filter Allocations by Tenant ID

includeRelation
string
Enum: "InfrastructureProvider" "Tenant" "Site"

Related entity to expand

Responses

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "allocationConstraints": [
    ]
}

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
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "Echo Studios Compute",
  • "description": "Echo Studios compute resource allocation in SJC4"
}

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "allocationConstraints": [
    ]
}

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 samples

Content type
application/json
[
  • {
    }
]

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
string
Enum: "InstanceType" "IPBlock"
resourceTypeId
required
string <uuid>
constraintType
required
string
Enum: "Reserved" "OnDemand" "Preemptible"
constraintValue
required
integer

Responses

Request samples

Content type
application/json
{
  • "resourceType": "InstanceType",
  • "resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
  • "constraintType": "Reserved",
  • "constraintValue": 10
}

Response samples

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": {
    },
  • "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 samples

Content type
application/json
[
  • {
    }
]

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

Responses

Request samples

Content type
application/json
{
  • "constraintValue": 20
}

Response samples

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": {
    },
  • "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 operations

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

status
string

Filter VPCs by Status

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

networkSecurityGroupId
string

Filter VPCs by NetworkSecurityGroup ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

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

object (Labels) <= 10 properties

String key value pairs describing VPC labels. Up to 10 key value pairs can be specified

Responses

Request samples

Content type
application/json
{
  • "name": "spark-vpc",
  • "description": "Virtual network for machines executing Spark jobs",
  • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
  • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  • "labels": {
    }
}

Response samples

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",
  • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  • "labels": {
    },
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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 samples

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",
  • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  • "labels": {
    },
  • "status": "Ready",
  • "networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e,",
  • "networkSecurityGroupPropagationDetails": {
    },
  • "statusHistory": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "name": "spark-vpc-v1",
  • "description": "Virtual network for machines executing Spark jobs v1",
  • "labels": {
    }
}

Response samples

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",
  • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  • "labels": {
    },
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "networkVirtualizationType": "FNN"
}

Response samples

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",
  • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  • "labels": {
    },
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

VPC Prefix

VPC Prefixes are networking constructs that connect a set of bare metal machines.

They are defined by a prefix and prefix length and can be a slice or the whole part of an IP Block allocated to a Tenant.

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 samples

Content type
application/json
[
  • {
    }
]

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
string <uuid>
prefixLength
required
integer

Responses

Request samples

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

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": [
    ],
  • "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 samples

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": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "name": "east-vpc-traffic-net"
}

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

Subnet

Subnets are networking constructs that connect a set of bare metal machines.

They are defined by a prefix and prefix length and can be a slice or the whole part of an IP Block allocated to a Tenant.

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 samples

Content type
application/json
[
  • {
    }
]

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

Request samples

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

Response samples

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": [
    ],
  • "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 samples

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": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "name": "spark-gpu-subnet",
  • "description": "Subnet for dedicated GPU nodes"
}

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

Expected Machine

Expected Machine operations allow Infrastructure Providers to pre-register machines that are expected to be discovered at a site.

Expected Machines contain BMC credentials and hardware identifiers to help with automated machine provisioning and management.

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)

bmcUsername
string or null <= 20 characters

Username for accessing the Expected Machine's BMC

bmcPassword
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

object (Labels) <= 10 properties

User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Request samples

Content type
application/json
{
  • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
  • "bmcUsername": "admin",
  • "bmcPassword": "password123",
  • "chassisSerialNumber": "CHASSIS-12345",
  • "fallbackDPUSerialNumbers": [
    ],
  • "labels": {
    }
}

Response samples

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": [
    ],
  • "skuId": "lenovo.sr650v2.cpu.1",
  • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  • "labels": {
    },
  • "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 samples

Content type
application/json
[
  • {
    }
]

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 samples

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": [
    ],
  • "skuId": "lenovo.sr650v2.cpu.1",
  • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  • "labels": {
    },
  • "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)

bmcUsername
string or null <= 20 characters

Username for accessing the Expected Machine's BMC

bmcPassword
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

object (Labels) <= 10 properties

User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Request samples

Content type
application/json
{
  • "bmcUsername": "newadmin",
  • "bmcPassword": "newpassword123",
  • "chassisSerialNumber": "CHASSIS-54321",
  • "labels": {
    }
}

Response samples

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": [
    ],
  • "skuId": "lenovo.sr650v2.cpu.1",
  • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  • "labels": {
    },
  • "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

Content type
application/json
{
  • "source": "carbide",
  • "message": "Error validating request data",
  • "data": {
    }
}

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)

bmcUsername
string or null <= 20 characters

Username for accessing the Expected Machine's BMC

bmcPassword
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

object (Labels) <= 10 properties

User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

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)

bmcUsername
string or null <= 20 characters

Username for accessing the Expected Machine's BMC

bmcPassword
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

object (Labels) <= 10 properties

User-defined key-value pairs for organizing and categorizing Expected Machines

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

SKU

SKU (Stock Keeping Unit) operations allow Infrastructure Providers to retrieve hardware configurations discovered at their sites.

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 samples

Content type
application/json
[
  • {
    }
]

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 samples

Content type
application/json
{
  • "id": "lenovo.sr650v2.cpu.1",
  • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  • "deviceType": "gpu",
  • "associatedMachineIds": [
    ],
  • "components": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

InfiniBand Partition

Partitions provide networking support for high-performance computing that features very high throughput and very low latency.

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 samples

Content type
application/json
[
  • {
    }
]

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

Responses

Request samples

Content type
application/json
{
  • "name": "turbo-net",
  • "siteId": "69dae3c8-3554-4a1f-b391-858c6dc47fff"
}

Response samples

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,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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 samples

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,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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

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

Responses

Request samples

Content type
application/json
{
  • "name": "turbo-net-v2",
  • "description": "Second version of the model training network"
}

Response samples

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,
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

Operating System

Operating System operations

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 samples

Content type
application/json
Example
[
  • {
    }
]

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>

Specified if a Provider owns the Operating System

tenantId
string or null <uuid>

Specified if a Tenant owns the Operating System

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

Request samples

Content type
application/json
Example
{
  • "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

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": [
    ],
  • "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 samples

Content type
application/json
Example
{
  • "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": [
    ],
  • "isActive": true,
  • "deactivationNote": null,
  • "status": "Syncing",
  • "statusHistory": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "name": "ubuntu-22.04-lts",
  • "description": "Ubuntu 22.04 LTS",
  • "allowOverride": true
}

Response samples

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": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

Instance Type

Instance Types allow grouping two or more Machines into a pool which can be specified when creating an Instance.

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.

siteId query param must be specified. Either infrastructureProviderId or tenantId query param must be specified.

If infrastructureProviderId query param is provided, then org must have an Infrastructure Provider entity that owns the Site specified by siteId in query param. User must have FORGE_PROVIDER_ADMIN role.

If tenantId query param is provided, then org must have a Tenant entity and it should have at least one Allocation with the Site specified by siteId in query param. User must have FORGE_TENANT_ADMIN role.

Authorizations:
JWTBearerToken
path Parameters
org
required
string

Name of the Org

query Parameters
siteId
required
string <uuid>

Filter Instance Types by Site ID

infrastructureProviderId
string <uuid>

Filter Instance Types by Infrastructure Provider ID

tenantId
string <uuid>

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. Currently can only be requested by Tenant

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 samples

Content type
application/json
Example
[
  • {
    }
]

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

Request samples

Content type
application/json
Example
{
  • "name": "x3.large",
  • "description": "Part of X family, the X3 Large features increased compute power",
  • "siteId": "8d97fa69-9199-49ff-bcf3-168c62d3874e",
  • "labels": {
    },
  • "machineCapabilities": [
    ]
}

Response samples

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": {
    },
  • "machineCapabilities": [
    ],
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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 samples

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": {
    },
  • "machineCapabilities": [
    ],
  • "allocationStats": {
    },
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "description": "Updated version of the X3 Large family of machines",
  • "labels": {
    },
  • "machineCapabilities": [
    ]
}

Response samples

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": {
    },
  • "machineCapabilities": [
    ],
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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 samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "machineIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Delete a Machine/Instance Type association

Delete a Machine's association with 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

machineAssociationId
required
string

ID of the Machine/Instance Type Association

Responses

Response samples

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 for a Tenant and attached to one or more 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.
  • allocationId was deprecated, and removed on September 6th, 2025 0:00 UTC.

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 samples

Content type
application/json
Example
[
  • {
    }
]

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

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)

Associate one or more NVLink Logical Partitions with this Instance

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

Specify list of SSH Key Group IDs that will provide Serial over LAN access

allowUnhealthyMachine
boolean

Must be set to true creating a targeted Instance with a Machine that is in Error status. Requires Targeted Instance Creation capability enabled for Tenant

Responses

Request samples

Content type
application/json
Example
{
  • "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": {
    },
  • "interfaces": [
    ],
  • "infinibandInterfaces": [
    ],
  • "nvLinkInterfaces": [
    ],
  • "sshKeyGroupIds": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "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": {
    },
  • "isUpdatePending": false,
  • "serialConsoleUrl": "ssh://user@carbide.acme.com",
  • "interfaces": [
    ],
  • "infinibandInterfaces": [
    ],
  • "nvLinkInterfaces": [
    ],
  • "dpuExtensionServiceDeployments": [ ],
  • "sshKeyGroupIds": [
    ],
  • "sshKeyGroups": [
    ],
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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

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.

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

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

Request samples

Content type
application/json
Example
{
  • "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": [
    ],
  • "infinibandInterfaces": [
    ],
  • "nvLinkInterfaces": [
    ],
  • "sshKeyGroupIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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 samples

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": {
    },
  • "networkSecurityGroupInherited": false,
  • "labels": {
    },
  • "isUpdatePending": false,
  • "serialConsoleUrl": "ssh://user@carbide.acme.com",
  • "interfaces": [
    ],
  • "infinibandInterfaces": [
    ],
  • "nvLinkInterfaces": [
    ],
  • "dpuExtensionServiceDeployments": [
    ],
  • "sshKeyGroupIds": [
    ],
  • "sshKeyGroups": [
    ],
  • "tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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

Content type
application/json
{
  • "machineHealthIssue": {
    },
  • "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.

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

Array of objects (DpuExtensionServiceDeploymentRequest)

Updated set of DPU Extension Services to deploy to the DPUs of this Instance

Responses

Request samples

Content type
application/json
{
  • "name": "spark-monitor-1",
  • "description": "Spark Monitor Node 1",
  • "triggerReboot": true,
  • "rebootWithCustomIpxe": true,
  • "applyUpdatesOnReboot": true,
  • "sshKeyGroupIds": [
    ],
  • "labels": {
    },
  • "interfaces": [
    ],
  • "infinibandInterfaces": [
    ],
  • "nvLinkInterfaces": [
    ],
  • "dpuExtensionServiceDeployments": [
    ]
}

Response samples

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": {
    },
  • "isUpdatePending": false,
  • "serialConsoleUrl": "ssh://user@carbide.acme.com",
  • "interfaces": [
    ],
  • "infinibandInterfaces": [
    ],
  • "dpuExtensionServiceDeployments": [
    ],
  • "sshKeyGroupIds": [
    ],
  • "sshKeyGroups": [
    ],
  • "tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
  • "status": "Rebooting",
  • "statusHistory": [
    ],
  • "deprecations": [
    ],
  • "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 samples

Content type
application/json
[
  • {
    }
]

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: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

Ordering for pagination query

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Retrieve all 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 Interfaces by Status

includeRelation
string
Enum: "Instance" "Partition"

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 samples

Content type
application/json
[
  • {
    }
]

Machine

Machine operations

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. siteId must be specified when using this param.

instanceTypeId
string

Filter Machines by Instance Type ID. Can be specified multiple times to filter on more than one Instance Type ID.

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 samples

Content type
application/json
[
  • {
    }
]

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 samples

Content type
application/json
Example
{
  • "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": [
    ],
  • "machineInterfaces": [
    ],
  • "maintenanceMessage": null,
  • "health": {
    },
  • "labels": {
    },
  • "status": "Ready",
  • "isUsableByTenant": true,
  • "statusHistory": [
    ],
  • "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

Request samples

Content type
application/json
Example
{
  • "instanceTypeId": "2e016c02-2c67-48aa-b289-5d3ca6320c52"
}

Response samples

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": [
    ],
  • "machineInterfaces": [
    ],
  • "maintenanceMessage": null,
  • "health": {
    },
  • "labels": {
    },
  • "status": "Ready",
  • "isUsableByTenant": true,
  • "statusHistory": [
    ],
  • "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

Content type
application/json
{
  • "source": "carbide",
  • "message": "Error validating request data",
  • "data": {
    }
}

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 samples

Content type
application/json
[
  • {
    }
]

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 samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Machine Capability

Machine Capability operations

Rack

Rack operations

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

model
string

Filter by model

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 samples

Content type
application/json
[
  • {
    }
]

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 samples

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": {
    },
  • "components": [
    ]
}

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, manufacturer, or model.

Compares the expected component configuration (stored in RLA) against the actual state from external systems (e.g., Carbide, PSM). 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

model
string

Filter racks by model

Responses

Response samples

Content type
application/json
Example
{
  • "diffs": [ ],
  • "totalDiffs": 0,
  • "onlyInExpectedCount": 0,
  • "onlyInActualCount": 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 (stored in RLA) against the actual state from external systems (e.g., Carbide, PSM). 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 samples

Content type
application/json
Example
{
  • "diffs": [ ],
  • "totalDiffs": 0,
  • "onlyInExpectedCount": 0,
  • "onlyInActualCount": 0,
  • "driftCount": 0,
  • "matchCount": 5
}

Network Security Group

Network Security Group operations

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 samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "name": "Spark VPC Firewall",
  • "description": "Security policies for machines in Spark VPC",
  • "siteId": "188a8f32-0001-45cf-b243-f62720a22cc4",
  • "rules": [
    ],
  • "labels": {
    }
}

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": [
    ],
  • "rules": [
    ],
  • "labels": {
    },
  • "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 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": [
    ],
  • "rules": [
    ],
  • "labels": {
    },
  • "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

Request samples

Content type
application/json
{
  • "name": "Spark VPC Firewall",
  • "description": "Security policies for machines in Spark VPC",
  • "rules": [
    ],
  • "labels": {
    }
}

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": [
    ],
  • "rules": [
    ],
  • "labels": {
    },
  • "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": {
    }
}

IP Block

IP Block is a set 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 blocks to Tenants.

Historic deprecations:

  • 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 samples

Content type
application/json
[
  • {
    }
]

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" "Datacenter Only"
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

Request samples

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

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": [
    ],
  • "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 samples

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": {
    },
  • "status": "Pending",
  • "statusHistory": [
    ],
  • "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

Content type
application/json
{
  • "source": "carbide",
  • "message": "Error validating request data",
  • "data": {
    }
}

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

Request samples

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

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": [
    ],
  • "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 samples

Content type
application/json
[
  • {
    }
]

DPU Extension Service

DPU Extension Service allows users to run custom services in the DPUs of their Instances

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 samples

Content type
application/json
[
  • {
    }
]

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

Responses

Request samples

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": {}
}

Response samples

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": {
    },
  • "activeVersions": [
    ],
  • "status": "Ready",
  • "statusHistory": [
    ],
  • "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 samples

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": {
    },
  • "activeVersions": [
    ],
  • "status": "Ready",
  • "statusHistory": [
    ],
  • "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

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

Responses

Request samples

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": {}
}

Response samples

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": {
    },
  • "activeVersions": [
    ],
  • "status": "Ready",
  • "statusHistory": [
    ],
  • "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 samples

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

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

Content type
application/json
{
  • "source": "carbide",
  • "message": "User is not allowed to perform this action",
  • "data": null
}

SSH Key Group

SSH Key Groups allow binding several SSH Keys together so they can be applied to Sites or other entities as a unit

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 samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "name": "reno-integration-sre",
  • "description": "SRE access SSH keys for Reno Integration",
  • "siteIds": [
    ],
  • "sshKeyIds": [
    ]
}

Response samples

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": [
    ],
  • "sshKeys": [
    ],
  • "status": "Syncing",
  • "statusHistory": [
    ],
  • "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 samples

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": [
    ],
  • "sshKeys": [
    ],
  • "status": "Syncing",
  • "statusHistory": [
    ],
  • "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

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

Request samples

Content type
application/json
{
  • "name": "reno-int-sre",
  • "description": "SRE access SSH keys for Reno Integration Site",
  • "siteIds": [
    ],
  • "sshKeyIds": [
    ],
  • "version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75"
}

Response samples

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": [
    ],
  • "sshKeys": [
    ],
  • "status": "Syncing",
  • "statusHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

SSH Key

SSH Key allows access to Serial Console

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 samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "name": "reno-sre-access",
  • "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICip4hl6WjuVHs60PeikVUs0sWE/kPhk2D0rRHWsIuyL jdoe@test.com",
  • "sshKeyGroupId": "86ca8cab-b285-4c2d-9e00-25c88810dc2e"
}

Response samples

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 samples

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

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

Request samples

Content type
application/json
{
  • "name": "reno-sre-access-v2"
}

Response samples

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 operations

Retrieve Current User

Retrieve details of the current user.

Authorizations:
JWTBearerToken
path Parameters
org
required
string

Name of the Org

Responses

Response samples

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 operations

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 samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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 samples

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": {
    },
  • "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 server

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 samples

Content type
application/json
{
  • "version": "0.1.24",
  • "buildTime": "2019-08-24T14:15:22Z"
}

Deprecations

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.
  • allocationId was deprecated, and removed on September 6th, 2025 0:00 UTC.

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.

Tray

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 samples

Content type
application/json
[
  • {
    }
]

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 samples

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": {
    },
  • "rackId": "550e8400-e29b-41d4-a716-446655440000"
}