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

ApiKeyAuth

X-Api-KeystringRequired

Body

application/json

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

400

Invalid json body supplied

401

Invalid authentication

404

No available server could be found for allocation

422

Invalid body parameter(s) supplied

application/json

post

/api/server/allocate

HTTPcURLJavaScriptPython

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

ApiKeyAuth

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

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

delete

/api/client/{clientId}/server/{serverId}/allocate

HTTPcURLJavaScriptPython

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

ApiKeyAuth

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

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

delete

/api/client/{clientId}/server/{serverId}/allocate/compensate

HTTPcURLJavaScriptPython

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

ApiKeyAuth

X-Api-KeystringRequired

Path parameters

serverIdinteger · intRequired

ID of the server to isolate

Body

application/jsonapplication/xml

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

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

post

/api/server/{serverId}/isolate

HTTPcURLJavaScriptPython

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

application/jsonapplication/xml

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

ApiKeyAuth

X-Api-KeystringRequired

Path parameters

serverIdinteger · intRequired

ID of the server to move out of isolation

Responses

200

Successful operation

application/json

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

delete

/api/server/{serverId}/isolate

HTTPcURLJavaScriptPython

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

ApiKeyAuth

X-Api-KeystringRequired

Path parameters

serverIdinteger · intRequired

ID of the server to set to Available

Responses

200

Successful operation

application/json

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

post

/api/server/{serverId}/available

HTTPcURLJavaScriptPython

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

ApiKeyAuth

X-Api-KeystringRequired

Path parameters

serverIdinteger · intRequired

ID of the server to quarantine

Responses

200

Successful operation

application/json

400

Invalid ID supplied

401

Invalid authentication

404

Server not found

post

/api/server/{serverId}/quarantine

HTTPcURLJavaScriptPython

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