Ctrlk
Go to i3D.netGet support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Server Commands

Commands you can perform on servers

Allocate a server to a client

post

Allocates a server to a client, according to the given location and instance type.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Body

Allocation request object

locationIdinteger · min: 1RequiredExample: 18
instanceTypeIdinteger · min: 1RequiredExample: 126
clientIdintegerRequiredExample: 12345
contractIdstringOptional

Can be empty or null for on-demand client quota

Example: JD-NB2UU6VX732Pattern: ^[A-Z0-9_\-.]{0,240}$
overflowbooleanOptional

If true, the allocation will be allowed to overflow the client's quota and use on-demand quota

Default: falseExample: false
Responses
200

Successful operation

application/json
post/api/server/allocate
POST /api/server/allocate HTTP/1.1
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "locationId": 18,
  "instanceTypeId": 126,
  "clientId": 12345,
  "contractId": "JD-NB2UU6VX732",
  "overflow": false
}
{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  },
  "quota": {
    "id": 123,
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "locationId": 18,
    "instanceTypeId": 123,
    "quota": 5
  }
}

De-allocate a server from a client

delete

De-allocates a server from a client. Afterwards the Back to Baseline process will start, wiping and health checking the server.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
clientIdinteger · intRequired

ID of the client to de-allocate for

serverIdinteger · intRequired

ID of the server to de-allocate

Responses
200

Successful operation. Returned in case of success, but also when the server was already de-allocated.

application/json
delete/api/client/{clientId}/server/{serverId}/allocate
DELETE /api/client/{clientId}/server/{serverId}/allocate HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Compensates allocation for a server

delete

Compensates Allocation of the server which failed to deliver. Afterwards the Back to Baseline process will start, wiping and health checking the server.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
serverIdinteger · intRequired

ID of the server to de-allocate

clientIdinteger · intRequired

ID of the client to de-allocate for

Responses
200

Successful operation

application/json
delete/api/client/{clientId}/server/{serverId}/allocate/compensate
DELETE /api/client/{clientId}/server/{serverId}/allocate/compensate HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Isolate a server with a specific reason (subState)

post

Isolate a server with a specific reason (subState). See request object for valid values.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
serverIdinteger · intRequired

ID of the server to isolate

Body

Isolation request object

subStatestring · enumRequiredExample: brokenHardwarePossible values:
operationUuidstring · uuidOptional

The operationUuid reference from MetalWorks

reasonstringOptionalExample: Failed to IPMI boot
Responses
200

Successful operation

application/json
post/api/server/{serverId}/isolate
POST /api/server/{serverId}/isolate HTTP/1.1
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "subState": "brokenHardware",
  "operationUuid": "123e4567-e89b-12d3-a456-426614174000",
  "reason": "Failed to IPMI boot"
}
{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Move a server out of isolation to start the baseline process

delete

Move a server out of isolation to start the baseline process after which it will become Available again or, if a problem was encountered during the baseline process, the server goes back to Isolation.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
serverIdinteger · intRequired

ID of the server to move out of isolation

Responses
200

Successful operation

application/json
delete/api/server/{serverId}/isolate
DELETE /api/server/{serverId}/isolate HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Set server status to Available

post

Set server status to Available. Should only be called by MetalWorks after a successful Back to Baseline workflow.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
serverIdinteger · intRequired

ID of the server to set to Available

Responses
200

Successful operation

application/json
post/api/server/{serverId}/available
POST /api/server/{serverId}/available HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Quarantine a server

post

Quarantines a server, preserving its current state, e.g. for law enforcement purposes or any "offline" investigation into a server's state.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-Api-KeystringRequired
Path parameters
serverIdinteger · intRequired

ID of the server to quarantine

Responses
200

Successful operation

application/json
post/api/server/{serverId}/quarantine
POST /api/server/{serverId}/quarantine HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "server": {
    "serverId": 79186,
    "machineUuid": "4c4c4544-0059-5810-8033-c8c04f584432",
    "serial": "HYX3XD2",
    "name": "Server 12653",
    "hostname": "host.example.com",
    "locationId": 18,
    "locationName": "EU: Rotterdam",
    "instanceTypeId": 126,
    "instanceTypeName": "bm1-std-4",
    "clientId": 12345,
    "contractId": "JD-NB2UU6VX732",
    "state": "isolated",
    "subState": "brokenHardware",
    "vendor": "Dell Inc.",
    "chassis": "PowerEdge R230",
    "firmwareVersion": 1.23,
    "ipmiVersion": 2,
    "ipAddresses": [
      {
        "ipAddress": "1.2.3.4",
        "ipType": "normal|bmc",
        "ipVersion": "v4|v6"
      }
    ],
    "macAddresses": [
      {
        "macAddress": "10:98:36:A0:80:33",
        "macType": "normal|bmc"
      }
    ],
    "disks": [
      {
        "name": "sda|nvmep0n1",
        "interface": "sata|nvme",
        "type": "hdd|ssd|sas|nvme"
      }
    ],
    "isolationReason": {
      "operationUuid": "0194bc95-e1a4-73a0-81be-ae17c3a7e92b",
      "reason": "Server encountered error in PXE ...",
      "createdAt": "2018-03-20T09:12:28.000Z"
    }
  }
}

Last updated

Was this helpful?