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.

Authentication

To work with the API, you must include your IBM Cloud IAM access token and the Power Systems Virtual Server instance ID in every request.

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.

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 is supported.

To retrieve your access token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey={API_KEY}" https://iam.bluemix.net/identity/token

Or using CLI:

ibmcloud iam oauth-tokens

Replace {API_KEY} with the API key. Then, use the full IAM token value, prefixed by the Bearer token type to authenticate your API requests.

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

The Power Systems Virtual Server API's use standard HTTP response codes to indicate whether a method completed successfully. A 200 HTTP response always indicates success. HTTP response codes with the format 4xx indicate a failure. A 500 HTTP response code usually indicates an internal system error that cannot be resolved by the user.

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.

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 an available image

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

Path Parameters

  • Image ID of a image

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

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

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 images for this cloud instance

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

Path Parameters

  • Cloud Instance ID of a PCloud Instance

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

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

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

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

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

Path Parameters

  • Tenant ID of a pcloud tenant

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Update a tenant

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

Path Parameters

  • Tenant ID of a pcloud tenant

Parameters for updating a Tenant

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

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

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

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

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

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

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

Path Parameters

  • Cloud Instance ID of a PCloud Instance

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Create a new data Volume

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

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

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

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

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Volume ID

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

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

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

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 PVMInstance

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

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 PVMInstance

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

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 PVMInstance

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

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 PVMInstance

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

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 Power VM Instance

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

Response

A list of PVMInstances

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

Response

Status Code

  • OK

  • Bad Request

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get a PVM Instance's current state/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

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

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

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 PVMInstance

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

Response

Status Code

  • OK

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Capture a PVMInstance 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

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

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

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

Response

Status Code

  • OK

  • Bad Request

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get a network's current state/information

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

Path Parameters

  • Cloud Instance ID of a PCloud Instance

  • Network ID

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

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

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

Response

Status Code

  • OK

  • Bad Request

  • Gone

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.