Introduction

The IBM Cloud™ Virtual Private Cloud (VPC) API is a RESTful API that lets you manage your VPC lifecycle and resources. Use the VPC API to provision instances with high network performance and fast port speeds.

This API is for use with generation 2 compute resource. Generation 2 resources aren't compatible with generation 1 resources. If you want to migrate your API scripts from generation 1 to generation 2, see API application migration considerations.

Familiarize yourself with VPC functionality described in About Virtual Private Cloud. See also the following topics:

Learn about setting up and managing a VPC in the following tutorials:

Authentication

The IBM Cloud VPC API uses Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

Authorization

Access management to VPC infrastructure resources is done through resource groups and IAM. The service VPC Infrastructure contains various resource types that can be controlled. Learn more about the required permissions for VPC resources.

API endpoint

The endpoint is based on the region of the service and follows the convention https://<region>.iaas.cloud.ibm.com.

Available endpoints by region:

Region name Region Endpoint
US South (Dallas) us-south https://us-south.iaas.cloud.ibm.com

Response model properties

Certain properties are included in API responses for all customer-created VPC resources. The created_at value is a timestamp that matches when the resource became visible through calls to the IBM Cloud™ Virtual Private Cloud API.

Versioning

All API requests require a major version in the path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD. For example:

GET /v1/regions?version=2019-09-30

Any date-based version, up to the current date, is supported. Start development of new applications with the current date as a fixed value. Don't dynamically use the current date as the version for a production application. Instead, use a fixed date-based version that has been tested with your application. Periodically check the release notes for API changes. Update and test your application with new version dates to maintain ongoing compatibility.

API changes

API improvements and fixes are documented in the the release notes, along with guidance on code updates required to use a new date-based version. By design, new features with backward-incompatible changes apply only to version dates on and after the feature's release. Changes that apply to older versions of the API are designed to maintain compatibility with existing applications and code.

Best practices

To minimize regressions from changes, IBM recommends the following best practices when calling the API:

  • Catch and log any 4xx or 5xx HTTP status code along with the included trace property
  • Follow HTTP redirect rules for any 3xx HTTP status code
  • Consume only the resources and properties needed for your application to function
  • Avoid depending on any behavior that is not explicitly documented

Generation

To use the IBM Cloud VPC infrastructure, send the generation=2 query parameter with every API request. For example, to create a VPC, run the following API call:

POST /v1/vpcs?generation=2`

Variables

Consider storing frequently-used values in a variable. Values you might want to save include the API endpoint, authorization token, API version, and other resource identifiers.

Example: To store the endpoint in a variable, run this command:

api_endpoint=https://us-south.iaas.cloud.ibm.com

To verify that the variable was saved, run echo $api_endpoint and make sure the response is not empty.

See the following topics for additional examples on setting variables:

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates some sort of failure, and a 500 type response usually indicates an internal server 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 '{namespace}'.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, and try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error IBM Cloud API is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests can return a large number of results. Optionally include limit or start parameters in an API request to page through your available resources and retrieve a subset of objects.

Parameter Description
limit Limits the number of objects to return, 1 to 100.

The default limit (typically 100) depends on the specific API call. If limit is omitted, the system returns up to 100 objects.

Example: List the first 5 keys: .../keys?limit=5
start Returns the next page of results.

If the response does not contain a link to the next page of results, you have reached the end.

Example: Start on the 6th page: .../keys?limit=5&start=5

Methods

List all floating IPs

This request retrieves all floating IPs in the region. Floating IPs allow inbound and outbound traffic from the Internet to an instance.

GET /floating_ips
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • A server-supplied token determining what resource to start the page on

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

Response

Status Code

  • The floating IPs were retrieved successfully.

Example responses

Reserve a floating IP

This request reserves a new floating IP.

POST /floating_ips
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The floating IP template

Example:
Response

Status Code

  • The floating IP was reserved successfully.

  • An invalid floating IP template was provided.

  • The specified target is in use by another floating IP.

Example responses

Release the specified floating IP

This request disassociates (if associated) and releases a floating IP. This operation cannot be reversed. For this request to succeed, the floating IP must not be required by another resource, such as a public gateway.

DELETE /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The floating IP was released successfully.

  • The specified floating IP could not be found.

  • The floating IP is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified floating IP

This request retrieves a single floating IP specified by the identifier in the URL.

GET /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The floating IP was retrieved successfully.

  • The specified floating IP could not be found.

Example responses

Update the specified floating IP

This request updates a floating IP's name and/or target.

PATCH /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The floating IP patch

Response

Status Code

  • The floating IP was updated successfully.

  • The supplied floating IP patch was invalid.

  • A floating IP with the specified identifier could not be found.

  • The specified target is in use by another floating IP.

Example responses

List all images

This request lists all images available in the region. An image provides source data for a volume. Images are either system-provided, or created from another source, such as importing from object storage.

GET /images
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • A server-supplied token determining what resource to start the page on

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

  • Filters the collection to images with the specified visibility

    Allowable values: [private,public]

Response

Status Code

  • Images retrieved successfully

Example responses

Create an image

This request creates a new image from an image template. The image template object is structured in the same way as a retrieved image, and contains the information necessary to create the new image. A URL to the image file on object storage must be provided.

POST /images
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The image template

Example:
Response

Status Code

  • Image created successfully

  • The supplied image template was invalid.

Example responses

Delete specified image

This request deletes an image. This operation cannot be reversed. System-provided images are not allowed to be deleted. An image with a status of pending, tentative, or deleting cannot be deleted.

DELETE /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The image deletion request was accepted.

  • The image is not allowed to be deleted.

  • An image with the specified identifier could not be found.

  • The image cannot be deleted in its current state.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified image

This request retrieves a single image specified by the identifier in the URL.

GET /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • Image retrieved successfully

  • An image with the specified identifier could not be found.

Example responses

Update specified image

This request updates an image with the information in a provided image patch. The image patch object is structured in the same way as a retrieved image and contains only the information to be updated. System-provided images are not allowed to be updated. An image with a status of deleting cannot be updated.

PATCH /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The image patch

Response

Status Code

  • Image updated successfully

  • The supplied image template was invalid.

  • The image is not allowed to be updated.

  • An image with the specified identifier could not be found.

  • The image cannot be updated in its current state.

Example responses

Retrieves all operating systems

This request retrieves all operating systems.

GET /operating_systems
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • A server-supplied token determining what resource to start the page on

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

Response

Status Code

  • The operating systems were retrieved successfully.

Example responses

Retrieves an operating system

This request retrieves a single operating system specified by the name in the URL.

GET /operating_systems/{name}
Request

Path Parameters

  • The operating system name

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The operating system was retrieved successfully.

  • An operating system with the specified name could not be found.

Example responses

List all instance profiles

This request lists all instance profiles available in the region. An instance profile specifies the performance characteristics and pricing model for an instance.

GET /instance/profiles
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • Instance profiles retrieved successfully

Example responses

Retrieve specified instance profile

This request retrieves a single instance profile specified by the name in the URL.

GET /instance/profiles/{name}
Request

Path Parameters

  • The instance profile name

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • Instance profile retrieved successfully

  • An instance profile with the specified name could not be found.

Example responses

List all instances

This request lists all instances in the region.

GET /instances
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

Response

Status Code

  • The instances were retrieved successfully.

Example responses

Create an instance

This request provisions a new instance from an instance template. The instance template object is structured in the same way as a retrieved instance, and contains the information necessary to provision the new instance. The instance is automatically started.

POST /instances
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The instance template

Example:
Response

Status Code

  • The instance was created successfully.

  • Invalid instance template provided

Example responses

Delete specified instance

This request deletes an instance. This operation cannot be reversed. Any floating IPs associated with the instance's network interfaces are implicitly disassociated.

DELETE /instances/{id}
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The instance was deleted successfully.

  • An instance with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve an instance

This request retrieves a single instance specified by the identifier in the URL.

GET /instances/{id}
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The instance was retrieved successfully.

  • An instance with the specified identifier could not be found.

Example responses

Update specified instance

This request updates an instance with the information in a provided instance patch. The instance patch object is structured in the same way as a retrieved instance and contains only the information to be updated.

PATCH /instances/{id}
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The instance patch

Response

Status Code

  • The instance was updated successfully.

  • The supplied instance patch was invalid.

  • An instance with the specified identifier could not be found.

Example responses

Retrieve configuration used to initialize the instance.

This request retrieves configuration variables used to initialize the instance, such as SSH keys and the Windows administrator password.

GET /instances/{id}/initialization
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The initialization configuration was retrieved successfully.

  • An instance with the specified identifier could not be found.

Example responses

Create an instance action

This request creates a new action which will be queued up to run as soon as any pending or running actions have completed.

POST /instances/{instance_id}/actions
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The instance action template

Response

Status Code

  • The action was created successfully and will run in the order it was received.

  • The specified action could not be created.

  • An instance with the specified identifier could not be found.

Example responses

List all network interfaces on an instance

This request lists all network interfaces on an instance. A network interface is an abstract representation of a network interface card and connects an instance to a subnet. While each network interface can attach to only one subnet, multiple network interfaces can be created to attach to multiple subnets. Multiple interfaces may also attach to the same subnet.

GET /instances/{instance_id}/network_interfaces
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The network interfaces were retrieved successfully.

  • An instance with the specified identifier could not be found.

Example responses

Create a network interface

This request creates a new network interface from a network interface template. Any subnet in the instance's VPC may be specified, even if it is already attached to another network interface. The network interface template object is structured in the same way as a retrieved network interface, and contains the information necessary to create the new network interface. Each primary and secondary address in the network interface must be contained by the specified subnet's CIDR blocks.

POST /instances/{instance_id}/network_interfaces
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The network interface template

Response

Status Code

  • The network interface was created successfully.

  • An invalid network interface template was provided.

  • An instance with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Delete specified network interface

This request deletes a network interface. This operation cannot be reversed. Any floating IPs associated with the network interface are implicitly disassociated. The primary network interface is not allowed to be deleted.

DELETE /instances/{instance_id}/network_interfaces/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • Network interface deleted successfully

  • The network interface is not allowed to be deleted.

  • A network interface with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve specified network interface

This request retrieves a single network interface specified by the identifier in the URL.

GET /instances/{instance_id}/network_interfaces/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The network interface was retrieved successfully.

  • A network interface with the specified identifier could not be found.

Example responses

Update a network interface

This request updates a network interface with the information in a provided network interface patch. The network interface patch object is structured in the same way as a retrieved network interface and can contain an updated name and/or port speed.

PATCH /instances/{instance_id}/network_interfaces/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The network interface patch

Response

Status Code

  • The network interface was updated successfully.

  • An invalid network interface patch was provided.

  • A network interface with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all floating IPs associated with a network interface

This request lists all floating IPs associated with a network interface.

GET /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The associated floating IPs were retrieved successfully.

  • A network interface with the specified identifier could not be found.

Example responses

Disassociate specified floating IP

This request disassociates the specified floating IP from the specified network interface

DELETE /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The floating IP was disassociated successfully.

  • The specified floating IP could not be disassociated.

  • The specified floating IP address is not associated with the network interface with the specified identifier

No Sample Response

This method does not specify any sample responses.

Retrieve associated floating IP

This request a retrieves a specified floating IP address if it is associated with the network interface and instance specified in the URL

GET /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The associated floating IP was retrieved successfully.

  • The floating IP address is not associated with a network interface with the specified identifier

Example responses

Associate a floating IP with a network interface

This request associates the specified floating IP with the specified network interface, replacing any existing association. For this request to succeed, the existing floating IP must not be required by another resource, such as a public gateway. A request body is not required, and if supplied, is ignored.

PUT /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request

Path Parameters

  • The instance identifier

  • The network interface identifier

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The floating IP was successfully associated with the network interface.

  • The specified floating IP could not be associated with the specified network interface.

  • An instance with the specified identifier could not be found.

Example responses

List all volumes attached to an instance

This request lists all volume attachments for an instance. A volume attachment connects a volume to an instance. Each instance may have many volume attachments but each volume attachment connects exactly one instance to exactly one volume.

GET /instances/{instance_id}/volume_attachments
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The volume attachments were retrieved successfully.

  • An instance with the specified identifier could not be found.

Example responses

Create a volume attachment, connecting a volume to an instance

This request creates a new volume attachment from a volume attachment template. The volume attachment template object is structured in the same way as a retrieved volume attachment, and contains the information necessary to create the new volume attachment. The creation of a new volume attachment connects a volume to an instance.

POST /instances/{instance_id}/volume_attachments
Request

Path Parameters

  • The instance identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The volume attachment template

Response

Status Code

  • The volume attachment was created successfully, attaching the specified volume to the instance.

  • The specified volume could not be attached to the specified instance, so a volume attachment was not created.

  • An instance with the specified identifier could not be found.

Example responses

Delete a volume attachment, detaching a volume from an instance

This request deletes a volume attachment. The deletion of a volume attachment detaches a volume from an instance.

DELETE /instances/{instance_id}/volume_attachments/{id}
Request

Path Parameters

  • The instance identifier

  • The volume attachment identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The volume attachment was deleted successfully, detaching its volume from the instance

  • A volume attachment with the specified identifier could not be found for the specified instance.

No Sample Response

This method does not specify any sample responses.

Retrieve specified volume attachment

This request retrieves a single volume attachment specified by the identifier in the URL.

GET /instances/{instance_id}/volume_attachments/{id}
Request

Path Parameters

  • The instance identifier

  • The volume attachment identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The volume attachment was retrieved successfully.

  • A volume attachment with the specified identifier could not be found for the specified instance.

Example responses

Update a volume attachment

This request updates a volume attachment with the information in a provided volume attachment patch. The volume attachment patch object is structured in the same way as a retrieved volume attachment and can contain an updated name.

PATCH /instances/{instance_id}/volume_attachments/{id}
Request

Path Parameters

  • The instance identifier

  • The volume attachment identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The volume attachment patch

Response

Status Code

  • The volume attachment was updated successfully.

  • An invalid volume attachment patch was provided.

  • A volume attachment with the specified identifier could not be found for the specified instance.

Example responses

List all keys

This request lists all keys. A key contains a public SSH key which may be installed on instances when they are created. Private keys are not stored.

GET /keys
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • A server-supplied token determining what resource to start the page on

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

Response

Status Code

  • The keys were retrieved successfully.

Example responses

Create a key

This request imports a new key from a key template containing a public SSH key.

POST /keys
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The key template

Response

Status Code

  • The key was created successfully.

  • An invalid key template was provided.

Example responses

Delete specified key

This request deletes a key. This operation cannot be reversed.

DELETE /keys/{id}
Request

Path Parameters

  • The key identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The key was deleted successfully.

  • The key could not be deleted.

  • A key with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve specified key

This request retrieves a single key specified by the identifier in the URL.

GET /keys/{id}
Request

Path Parameters

  • The key identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The key was retrieved successfully.

  • A key with the specified identifier could not be found.

Example responses

Update specified key

This request updates a key's name.

PATCH /keys/{id}
Request

Path Parameters

  • The key identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The key patch

Response

Status Code

  • The key was updated successfully.

  • The supplied key patch was invalid.

  • A key with the specified identifier could not be found.

Example responses

List all public gateways

This request lists all public gateways. A public gateway is a virtual network device associated with a VPC, which allows access to the Internet. A public gateway resides in a zone and can be connected to subnets in the same zone only.

GET /public_gateways
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • A server-supplied token determining what resource to start the page on

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

Response

Status Code

  • The public gateways were retrieved successfully.

Example responses

Create a public gateway

This request creates a new public gateway from a public gateway template. If a floating IP is provided, it must be unbound. If a floating IP is not provided, one will be created and bound to the public gateway. Once a public gateway has been created, its floating IP cannot be unbound. A public gateway must be explicitly attached to each subnet it will provide connectivity for.

POST /public_gateways
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The public gateway template

Response

Status Code

  • The public gateway was created successfully.

  • An invalid public gateway template was provided.

Example responses

Delete specified public gateway

This request deletes a public gateway. This operation cannot be reversed. For this request to succeed, the public gateway must not be attached to any subnets. The public gateway's floating IP will be automatically unbound. If the floating IP was created when the public gateway was created, it will be deleted.

DELETE /public_gateways/{id}
Request

Path Parameters

  • The public gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The public gateway was deleted successfully.

  • A public gateway with the specified identifier could not be found.

  • The public gateway is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve specified public gateway

This request retrieves a single public gateway specified by the identifier in the URL.

GET /public_gateways/{id}
Request

Path Parameters

  • The public gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response