Introduction

You can use the IBM® Power Systems™ Virtual Server on IBM Cloud to quickly and easily deploy virtual servers that are running AIX or IBM i workloads. You can use the REST APIs to manage and configure the Power Systems Virtual Server.

Endpoint URL

The Power Systems Virtual Server service uses regional endpoints. To target your region, replace {region} with the prefix that represents the geographic area where your service instance resides. Currently, only us-east, us-south, and eu-de are supported.

https://{region}.power-iaas.cloud.ibm.com

Authentication

To work with the API, you must include your IBM Cloud IAM access token and the Power Systems Virtual Server instance ID, also known as your Cloud Resource Name (CRN), in every request. The first part of your CRN contains your Tenant ID and the second part contains your Cloud Instance ID. The following is an example of a typical CRN:

crn:v1:staging:public:power-iaas:us-east:a/abcdefghijklmnopqrstuvwxyzabcdef:121d5ee5-b87d-4a0e-86b8-aaff422135478::

abcdefghijklmnopqrstuvwxyzabcdef = Tenant ID {tenant_id}
121d5ee5-b87d-4a0e-86b8-aaff422135478 = Cloud Instance ID {cloud_instance_id}

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Retrieving an access token programmatically and Retrieving your instance ID.

API endpoint

https://{region}.power-iaas.cloud.ibm.com

Replace {region} with the prefix that represents the geographic area where your Power Systems Virtual Server service instance resides. Currently, only us-east, us-south, and eu-de are supported.

To retrieve your access token using the CLI:

ibmcloud iam oauth-tokens

To retrieve your instance ID:

ibmcloud resource service-instance {instance_name} --id

Replace {instance_name} with the unique alias that you assigned to your Power Systems Virtual Server instance.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access this resource.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error Power Systems Virtual Server is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Methods

List all images available for copying into Cloud Instances

GET /pcloud/v1/images
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/images \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "creationDate": "2019-07-10T13:42:30.000Z",
      "description": "",
      "href": "/pcloud/v1/images/792c4a2f-e67b-4885-bab7-10b588e355e4",
      "imageID": "792c4a2f-e67b-4885-bab7-10b588e355e4",
      "lastUpdateDate": "2019-11-05T20:50:14.000Z",
      "name": "7100-05-04",
      "specifications": {
        "architecture": "ppc64",
        "containerFormat": "bare",
        "diskFormat": "raw",
        "endianness": "big-endian",
        "hypervisorType": "phyp",
        "operatingSystem": "aix"
      }
    }

Detailed information of an available image

GET /pcloud/v1/images/{image_id}
Request

Path Parameters

  • Image ID of a image

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/images/{image_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "creationDate": "2019-09-11T16:10:00.000Z",
      "imageID": "b39f1013-6d26-4585-856d-8aa4ea5e9ee9",
      "lastUpdateDate": "2019-09-11T16:10:17.000Z",
      "name": "7200-03-03",
      "servers": [
        "mpb-api-test",
        "kylej-pointer-test",
        "dl02-test",
        "nni-vm01",
        "gre-vm02"
      ],
      "size": 20,
      "specifications": {
        "architecture": "ppc64",
        "containerFormat": "bare",
        "diskFormat": "raw",
        "endianness": "big-endian",
        "hypervisorType": "phyp",
        "imageType": "stock",
        "operatingSystem": "aix"
      },
      "state": "active",
      "storageType": "standard",
      "volumes": [
        {
          "bootable": true,
          "name": "volume-969afb22cb00-23977--cf758b7d-e30b",
          "size": 20
        }
      ]
    }

Create a new image (from available images)

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/images
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

Parameters for the creation of a new image from available images

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/images \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "source": "root-project"
            "imageID": "b39f1013-6d26-4585-856d-8aa4ea5e9ee9",
            "imageName": aix-test-image
          }'
Response

Status Code

  • OK

  • Created

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

List all of the images for this cloud instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/images
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/images \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "images": [
        {
          "creationDate": "2019-12-04T19:45:48.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/938b1104-18bc-4666-a384-b205793aab86",
          "imageID": "938b1104-18bc-4666-a384-b205793aab86",
          "lastUpdateDate": "2019-12-04T19:46:19.000Z",
          "name": "7100-05-04",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "stock",
            "operatingSystem": "aix"
          },
          "state": "active",
          "storageType": "tier3-gen2"
        },
        {
          "creationDate": "2019-09-11T16:10:00.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/b39f1013-6d26-4585-856d-8aa4ea5e9ee9",
          "imageID": "b39f1013-6d26-4585-856d-8aa4ea5e9ee9",
          "lastUpdateDate": "2019-09-11T16:10:17.000Z",
          "name": "7200-03-03",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "stock",
            "operatingSystem": "aix"
          },
          "state": "active",
          "storageType": "tier3-gen2"
        },
        {
          "creationDate": "2020-01-08T20:35:36.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/e3c453a9-40b0-4fd6-89f9-3b71273446b0",
          "imageID": "e3c453a9-40b0-4fd6-89f9-3b71273446b0",
          "lastUpdateDate": "2020-01-08T20:45:09.000Z",
          "name": "COS-import-7100-05-04-img",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "import",
            "operatingSystem": "aix"
          },
          "state": "active",
          "storageType": "standard"
        },
        {
          "creationDate": "2019-12-05T18:13:27.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/affa57fc-493d-4599-bfb6-755f99c9cab6",
          "imageID": "affa57fc-493d-4599-bfb6-755f99c9cab6",
          "lastUpdateDate": "2019-12-05T18:14:14.000Z",
          "name": "IBMi-72-09-002",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "stock",
            "operatingSystem": "ibmi"
          },
          "state": "active",
          "storageType": "standard"
        },
        {
          "creationDate": "2019-09-17T10:55:13.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/8105a084-0360-478f-bfe8-c5a2af98f690",
          "imageID": "8105a084-0360-478f-bfe8-c5a2af98f690",
          "lastUpdateDate": "2019-09-17T10:55:41.000Z",
          "name": "IBMi-73-06-001",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "stock",
            "operatingSystem": "ibmi"
          },
          "state": "active",
          "storageType": "tier3-gen2"
        },
        {
          "creationDate": "2019-11-04T22:26:04.000Z",
          "description": "",
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/images/75be671c-9e45-49c0-b462-7672e28fc80c",
          "imageID": "75be671c-9e45-49c0-b462-7672e28fc80c",
          "lastUpdateDate": "2019-11-04T22:27:14.000Z",
          "name": "IBMi-74-00-001",
          "specifications": {
            "architecture": "ppc64",
            "containerFormat": "bare",
            "diskFormat": "raw",
            "endianness": "big-endian",
            "hypervisorType": "phyp",
            "imageType": "stock",
            "operatingSystem": "ibmi"
          },
          "state": "active",
          "storageType": "tier3-gen2"
        }
      ]
    }

Detailed information of an image

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Image ID of a image

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "creationDate": "2019-09-11T16:10:00.000Z",
      "imageID": "b39f1013-6d26-4585-856d-8aa4ea5e9ee9",
      "lastUpdateDate": "2019-09-11T16:10:17.000Z",
      "name": "7200-03-03",
      "servers": [
        "kylej-pointer-test",
        "dl02-test",
        "nni-vm01",
        "gre-vm02"
      ],
      "size": 20,
      "specifications": {
        "architecture": "ppc64",
        "containerFormat": "bare",
        "diskFormat": "raw",
        "endianness": "big-endian",
        "hypervisorType": "phyp",
        "imageType": "stock",
        "operatingSystem": "aix"
      },
      "state": "active",
      "storageType": "standard",
      "volumes": [
        {
          "bootable": true,
          "name": "volume-969afb22cb00-23977--cf758b7d-e30b",
          "size": 20
        }
      ]
    }

Delete an image from a Cloud Instance

DELETE /pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Image ID of a image

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Export an image

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id}/export
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Image ID of a image

Parameters for exporting an image

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/images/{image_id}/export \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "bucketName": "cloud-object-storage-bucket",
            "accessKey": "347aa3a4b34344f8bc7c7cccdf856e4c"
          }'
Response

Status Code

  • Accepted

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get a tenant's current state or information

GET /pcloud/v1/tenants/{tenant_id}
Request

Path Parameters

  • Tenant ID of a pcloud tenant

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "cloudInstances": [
        {
          "cloudInstanceID": "78ea9383b1354924bdf97a3057f50110",
          "enabled": true,
          "href": "/pcloud/v1/cloud-instances/78ea9383b1354924bdf97a3057f50110",
          "initialized": false,
          "limits": {
            "instanceMemory": 0,
            "instanceProcUnits": 0,
            "instances": 0,
            "memory": 0,
            "peeringBandwidth": 0,
            "peeringNetworks": 0,
            "procUnits": 0,
            "processors": 0,
            "storage": 0,
            "storageSSD": 0
          },
          "name": "0d8f8fc5-5975-4e78-b541-aec77672ae51",
          "region": "us-east"
        },
        {
          "cloudInstanceID": "7c3d5c3f746c457a95ce3cebba76cf63",
          "enabled": true,
          "href": "/pcloud/v1/cloud-instances/7c3d5c3b746c457a95ce3bebba76cf63",
          "initialized": false,
          "limits": {
            "instanceMemory": 0,
            "instanceProcUnits": 0,
            "instances": 0,
            "memory": 0,
            "peeringBandwidth": 0,
            "peeringNetworks": 0,
            "procUnits": 0,
            "processors": 0,
            "storage": 0,
            "storageSSD": 0
          },
          "name": "37c24ed2-fd6a-4f4b-9119-f6a2817f1d58",
          "region": "us-east"
        },
        {
          "cloudInstanceID": "969afb22cb004e808cb84b827abfa1b0",
          "enabled": true,
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0",
          "initialized": false,
          "limits": {
            "instanceMemory": 0,
            "instanceProcUnits": 0,
            "instances": 0,
            "memory": 0,
            "peeringBandwidth": 0,
            "peeringNetworks": 0,
            "procUnits": 0,
            "processors": 0,
            "storage": 0,
            "storageSSD": 0
          }
        }
      ],
      "name": "781d5ef5-b87c-4a0a-86b8-aaa41213477",
      "region": "us-east",
      "creationDate": "2019-06-21T16:29:17.670Z",
      "enabled": true,
      "sshKeys": [
        {
          "creationDate": "2019-09-20T18:11:04.508Z",
          "name": "ibm-test",
          "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAA..."
        },
        {
          "creationDate": "2019-11-12T13:16:21.811Z",
          "name": "default-key-DO_NOT_DELETE",
          "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAA...a459814@FR-MP144WBV"
        },
        {
          "creationDate": "2019-11-21T09:40:47.042Z",
          "name": "e2e1574329171394",
          "sshKey": "abc"
        },
        {
          "creationDate": "2019-11-21T10:04:23.684Z",
          "name": "e2e1574330594605",
          "sshKey": "abc"
        }
      ],
      "tenantID": "efe5e8b9d3f04b948790fe5499bd18bc"
    }

Update a tenant

PUT /pcloud/v1/tenants/{tenant_id}
Request

Path Parameters

  • Tenant ID of a pcloud tenant

Parameters for updating a Tenant

  • curl -X PUT \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "sshKeys": {
              "name": "sshkey-name"
              "sshKey": "ssh-rsa-key"
            }
          }'
Response

Status Code

  • OK

  • Bad Request

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Add a new SSH key to the tenant

POST /pcloud/v1/tenants/{tenant_id}/sshkeys
Request

Path Parameters

  • Tenant ID of a pcloud tenant

Parameters for the creation of a new SSH key

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id}/sshkeys \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "sshkey-name"
            "sshKey": "ssh-rsa-key"
          }'
Response

Status Code

  • OK

  • Created

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

List a tenant's SSH Keys

GET /pcloud/v1/tenants/{tenant_id}/sshkeys
Request

Path Parameters

  • Tenant ID of a pcloud tenant

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id}/sshkeys \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "sshKeys": [
        {
          "creationDate": "2019-09-20T18:11:04.508Z",
          "name": "ibm-test",
          "sshKey": "ssh-rsa AAAAB3..."
        },
        {
          "creationDate": "2019-11-12T13:16:21.811Z",
          "name": "default-key-DO_NOT_DELETE",
          "sshKey": "ssh-rsa AAAAB..."
        }
      ]
    }

Get a tenant's SSH Key by name

GET /pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name}
Request

Path Parameters

  • Tenant ID of a pcloud tenant

  • SSH key name for a pcloud tenant

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update an SSH Key

PUT /pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name}
Request

Path Parameters

  • Tenant ID of a pcloud tenant

  • SSH key name for a pcloud tenant

Parameters for updating a Tenant's SSH Key

  • curl -X PUT \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "sshkey-name"
            "sshKey": "ssh-rsa-key"
          }'
Response

Status Code

  • OK

  • Bad Request

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete a tenant's SSH key

DELETE /pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name}
Request

Path Parameters

  • Tenant ID of a pcloud tenant

  • SSH key name for a pcloud tenant

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/tenants/{tenant_id}/sshkeys/{sshkey_name} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get a Cloud Instance's current state or information

GET /pcloud/v1/cloud-instances/{cloud_instance_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "cloudInstanceID": "969afb22cb004e808ab84b827abfa1b0",
      "enabled": true,
      "initialized": false,
      "limits": {
        "instanceMemory": 0,
        "instanceProcUnits": 0,
        "instances": 0,
        "memory": 0,
        "peeringBandwidth": 0,
        "peeringNetworks": 0,
        "procUnits": 0,
        "processors": 0,
        "storage": 0,
        "storageSSD": 0
      },
      "name": "781d5ee5-b87c-4a0a-86b8-aaa422135477",
      "openstackID": "10fd1a02-bed3-414a-9bfd-68a0ef9504dd",
      "pvmInstances": [
        {
          "addresses": [
            {
              "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/6da0fd14-f7d3-4142-96f5-078df36c2539/networks/testMangala",
              "ip": "172.16.5.168",
              "ipAddress": "172.16.5.168",
              "macAddress": "fa:a0:34:00:14:20",
              "networkName": "testMangala",
              "type": "fixed",
              "version": 4
            }
          ],
          "creationDate": "2019-11-21T10:41:33.000Z",
          "health": {
            "lastUpdate": "2019-11-21T15:59:12.842402",
            "status": "WARNING"
          },
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/6da0fd14-f7d3-4142-96f5-078df36c2539",
          "networks": [
            {
              "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/6da0fd14-f7d3-4142-96f5-078df36c2539/networks/testMangala",
              "ip": "172.16.5.168",
              "ipAddress": "172.16.5.168",
              "macAddress": "fa:a0:34:00:14:20",
              "networkName": "testMangala",
              "type": "fixed",
              "version": 4
            }
          ],
          "pvmInstanceID": "6da0fd14-f7d3-4142-96f5-078df36c2539",
          "serverName": "testr",
          "status": "ACTIVE",
          "sysType": "s922",
          "updatedDate": "2019-11-21T10:41:33.000Z"
        }
      ]
    }

Create a new data volume

The us-east (WDC) and us-south (DAL) regions use Standard or SSD storage types. The eu-de (FRA04 and FRA05) region uses Tier 1 (NVMe-based flash storage) or Tier 3 (SSD flash storage) storage types.

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/volumes
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

Parameters for the creation of a new data volume

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/volumes \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "diskType": "ssd"
            "name": "volume-name"
            "size": "volume-size"
          }'
Response

Status Code

  • Accepted

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

List all volumes for this cloud instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/volumes
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/volumes \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "bootVolume": false,
      "bootable": true,
      "creationDate": "2019-11-21T10:41:38.000Z",
      "diskType": "standard",
      "href": "/pcloud/v1/cloud-instances/969afb22cb004e807ab84b827abfa1b0/volumes/8a78e4b2-fc59-473e-9260-51a753634fd9",
      "lastUpdateDate": "2019-11-21T10:42:16.000Z",
      "name": "testr-6da0fd14-00000953-boot-0",
      "shareable": false,
      "size": 20,
      "state": "in-use",
      "volumeID": "8a78e4b2-fc59-473e-9260-51a753634fd9"
    }

Detailed information of a volume

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Volume ID

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "bootable": false,
      "creationDate": "2020-01-10T16:43:39.000Z",
      "diskType": "standard",
      "lastUpdateDate": "2020-01-13T17:58:45.000Z",
      "name": "tim-data-vol-4",
      "shareable": false,
      "size": 32,
      "state": "in-use",
      "volumeID": "e8cc1226-a4d5-46c8-875c-312b8b5bdda6"
    }

Update a cloud instance volume

PUT /pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Volume ID

Parameters to update a cloud instance volume

  • curl -X PUT \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "volume-name"
            "size": "volume-size"
          }'
Response

Status Code

  • OK

  • Bad Request

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete a cloud instance volume

DELETE /pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Volume ID

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

List all volumes attached to a PVM Instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Detailed info of a volume attached to a PVM Instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • Volume ID

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Attach a volume to a PVM Instance

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • Volume ID

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Conflict

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Detach a volume from a PVM Instance

DELETE /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • Volume ID

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/volumes/{volume_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Conflict

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Create a new PVM Instance

The order of network IDs passed in will be the order of interfaces defined to the VM.

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

Parameters for the creation of a new tenant

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "serverName": "server-name"
            "imageID": "image-id"
            "processors" "number-of-processors"
            "procType": "dedicated"
            "memory": "amount-of-memory"
            "networkIDs": "list-network-ids"
            }
          }'
Response

A list of PVMInstances

Status Code

  • OK

  • Created

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

Example responses
  • {
      "addresses": [
        {
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/35c0e26c-e51f-4230-b556-49ada44d8831/networks/64782dfc-820f-45e7-9975-7320a548f116",
          "ip": "192.168.2.153",
          "ipAddress": "192.168.2.153",
          "macAddress": "fa:f2:5f:3c:86:20",
          "networkID": "64782dfc-820f-45e7-9975-7320a548f116",
          "networkName": "MoyTest",
          "type": "fixed",
          "version": 4
        }
      ],
      "creationDate": "2020-01-17T05:55:28.000Z",
      "diskSize": 80,
      "health": {
        "lastUpdate": "2020-01-17T17:23:04.070950",
        "status": "OK"
      },
      "imageID": "8105a084-0360-478f-bfe8-c5a2af98f690",
      "maxmem": 4,
      "maxproc": 0.5,
      "memory": 2,
      "migratable": false,
      "minmem": 2,
      "minproc": 0.25,
      "networkIDs": [
        "64782dfc-820f-45e7-9975-7320a548f116"
      ],
      "networks": [
        {
          "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/35c0e26c-e51f-4230-b556-49ada44d8831/networks/64782dfc-820f-45e7-9975-7320a548f116",
          "ip": "192.168.2.153",
          "ipAddress": "192.168.2.153",
          "macAddress": "fa:f2:5f:3c:86:20",
          "networkID": "64782dfc-820f-45e7-9975-7320a548f116",
          "networkName": "MoyTest",
          "type": "fixed",
          "version": 4
        }
      ],
      "procType": "shared",
      "processors": 0.25,
      "pvmInstanceID": "35c0e26c-e51f-4230-b556-49ada44d8831",
      "serverName": "MoyMetadataTest3",
      "status": "ACTIVE",
      "storageType": "standard",
      "sysType": "s922",
      "updatedDate": "2020-01-17T05:55:28.000Z",
      "volumeIDs": [
        "3a40ee8a-e80c-49bc-9db4-b09687c38bd1"
      ]
    }

Get all the PVM Instances for this cloud instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Internal Server Error

Example responses
  • {
      "addresses": {
        "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/6da0fd14-f7d3-4142-96f5-078df36c2539/networks/testMangala",
        "ip": "172.16.5.168",
        "ipAddress": "172.16.5.168",
        "macAddress": "fa:a0:34:00:14:20",
        "networkName": "ibm-test-network",
        "type": "fixed",
        "version": 4
      },
      "creationDate": "2019-11-21T10:41:33.000Z",
      "health": {
        "lastUpdate": "2019-11-21T16:31:09.443463",
        "status": "WARNING"
      },
      "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/pvm-instances/6da0fd14-f7d3-4142-96f5-078df36c2539",
      "imageID": "732a5136-10b0-4c65-8882-7dc46601f3d5"
    }

Get a PVM Instance's current state or information

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update a PCloud PVM Instance

PUT /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

Parameters to update a PCloud PVM Instance

  • curl -X PUT \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • Accepted (this is a long running operation)

  • Bad Request

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete a PCloud PVM Instance

DELETE /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Perform an action (start stop reboot) on a PVM Instance

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/action
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

Parameters for the desired action

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/action \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "action": "start"
          }'
Response

Status Code

  • OK

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Capture a PVM Instance and create a deployable image

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/capture
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

Parameters for the capture PVMInstance

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/capture \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
              "captureName": "deployable-image-name"
              "captureDestination": "deployable-image-destination"
          }'
Response

Status Code

  • OK

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Generate the noVNC Console URL

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/console
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • PCloud PVM Instance ID

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}/console \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • Created

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Create a new network

POST /pcloud/v1/cloud-instances/{cloud_instance_id}/networks
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

Parameters for the creation of a new network

  • curl -X POST \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/networks \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
              "type": "vlan"
          }'
Response

Status Code

  • OK

  • Created

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get all networks in this cloud instance

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/networks
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/networks \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Internal Server Error

Example responses
  • {
      "href": "/pcloud/v1/cloud-instances/969afb22cb004e808ab84b827abfa1b0/networks/392913e3-e8ac-406b-a061-b431ee4bd239",
      "name": "test-ibm-network",
      "networkID": "392913e3-e8ac-406b-a061-b431ee4bd239",
      "type": "vlan",
      "vlanID": 3314
    }

Get a network's current state or information

GET /pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Network ID

  • curl -X GET \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses
  • {
      "cidr": "172.16.5.0/24",
      "dnsServers": [
        "9.9.9.9",
        "127.0.0.3"
      ],
      "gateway": "172.16.5.1",
      "ipAddressMetrics": {
        "available": 250,
        "total": 251,
        "used": 1,
        "utilization": 0
      },
      "ipAddressRanges": [
        {
          "endingIPAddress": "172.16.5.254",
          "startingIPAddress": "172.16.5.4"
        }
      ],
      "name": "testMangala1",
      "networkID": "392913e3-e8ac-406b-a061-b431ee4bd239",
      "type": "vlan",
      "vlanID": 3314
    }

Update a network

PUT /pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Network ID

Parameters to update a Network

  • curl -X PUT \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json' \
      -d '{
            "ipAddressRanges": {
              "startingIPAddress": "192.168.100.4"
              "endingIPAddress": "192.168.103.254"
            }
          }'
Response

Status Code

  • OK

  • Bad Request

  • Unprocessable Entity

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Delete a network

DELETE /pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id}
Request

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Network ID

  • curl -X DELETE \
      https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/{cloud_instance_id}/networks/{network_id} \
      -H 'Authorization: Bearer <>' \
      -H 'CRN: crn:v1...' \
      -H 'Content-Type: application/json'
Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.