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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses

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

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

Example responses

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

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

Example 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

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

Example 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

Example responses

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

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

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

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

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

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

Response

A list of PVMInstances

Status Code

  • OK

  • Created

  • Bad Request

  • Conflict

  • Unprocessable Entity

  • Internal Server Error

Example 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

Example responses

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

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

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

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

Example responses

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

Response

Status Code

  • OK

  • Bad Request

  • Not Found

  • Internal Server Error

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