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

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 API change log for API changes. Update and test your application with new version dates to maintain ongoing compatibility.

For more information, see Versioning in the IBM Cloud Platform API Implementation Handbook.

API changes

API improvements and fixes are documented in the API change log, 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 bugs caused by changes, follow these best practices when you call 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 be 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 IKE policies

This request retrieves a paginated list of all IKE policies that belong to this account.

GET /ike_policies
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 IKE policies were retrieved successfully.

Example responses

Create an IKE policy

This request creates a new IKE policy.

POST /ike_policies
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 IKE policy template.

Response

Status Code

  • The IKE policy was created successfully.

  • An invalid IKE policy template was provided.

Example responses

Delete an IKE policy

This request deletes an IKE policy. This operation cannot be reversed.

DELETE /ike_policies/{id}
Request

Path Parameters

  • The IKE policy 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 IKE policy was deleted successfully.

  • An IKE policy with the specified identifier could not be found.

  • The IKE policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified IKE policy

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

GET /ike_policies/{id}
Request

Path Parameters

  • The IKE policy 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 IKE policy was retrieved successfully.

  • An IKE policy with the specified identifier could not be found.

Example responses

Update an IKE policy

This request updates the properties of an existing IKE policy.

PATCH /ike_policies/{id}
Request

Path Parameters

  • The IKE policy 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 IKE policy patch.

Response

Status Code

  • The IKE policy was updated successfully.

  • An invalid IKE policy patch was provided.

  • An IKE policy with the specified identifier could not be found.

Example responses

Lists all the connections that use the specified policy

This request lists all the connections that use the specified policy.

GET /ike_policies/{id}/connections
Request

Path Parameters

  • The IKE policy 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

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

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

No Sample Response

This method does not specify any sample responses.

List all IPsec policies

This request retrieves a paginated list of all IPsec policies that belong to this account.

GET /ipsec_policies
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 IPsec policies were retrieved successfully.

Example responses

Create an IPsec policy

This request creates a new IPsec policy.

POST /ipsec_policies
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 IPsec policy template.

Response

Status Code

  • The IPsec policy was created successfully.

  • An invalid IPsec policy template was provided.

Example responses

Delete an IPsec policy

This request deletes an IPsec policy. This operation cannot be reversed.

DELETE /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy 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 IPsec policy was deleted successfully.

  • An IPsec policy with the specified identifier could not be found.

  • The IPsec policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified IPsec policy

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

GET /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy 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 IPsec policy was retrieved successfully.

  • An IPsec policy with the specified identifier could not be found.

Example responses

Update an IPsec policy

This request updates the properties of an existing IPsec policy.

PATCH /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy 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 IPsec policy patch.

Response

Status Code

  • The IPsec policy was updated successfully.

  • An invalid IPsec policy patch was provided.

  • An IPsec policy with the specified identifier could not be found.

Example responses

Lists all the connections that use the specified policy

This request lists all the connections that use the specified policy.

GET /ipsec_policies/{id}/connections
Request

Path Parameters

  • The IPsec policy 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

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

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

No Sample Response

This method does not specify any sample responses.

List all VPN gateways

This request retrieves a paginated list of all VPN gateways that belong to this account.

GET /vpn_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 VPN gateways were retrieved successfully.

Example responses

Create a VPN gateway

This request creates a new VPN gateway.

POST /vpn_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 VPN gateway template.

Response

Status Code

  • The VPN gateway was created successfully.

  • An invalid VPN gateway template was provided.

Example responses

Delete a VPN gateway

This request deletes a VPN gateway. A VPN gateway with a status of pending cannot be deleted. This operation deletes all VPN connections associated with this VPN gateway. This operation cannot be reversed.

DELETE /vpn_gateways/{id}
Request

Path Parameters

  • The VPN 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 VPN gateway deletion request has been accepted.

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

  • The VPN gateway is not allowed to be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified VPN gateway

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

GET /vpn_gateways/{id}
Request

Path Parameters

  • The VPN 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 VPN gateway was retrieved successfully.

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

Example responses

Update a VPN gateway

This request updates the properties of an existing VPN gateway.

PATCH /vpn_gateways/{id}
Request

Path Parameters

  • The VPN 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]

The VPN gateway patch.

Response

Status Code

  • The VPN gateway was updated successfully.

  • An invalid VPN gateway patch was provided.

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

Example responses

List all the connections of a VPN gateway

This request lists all the connections of a particular VPN gateway.

GET /vpn_gateways/{vpn_gateway_id}/connections
Request

Path Parameters

  • The VPN 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]

  • Filters the collection to VPN connections with the specified status

Response

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

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

Example responses

Create a VPN connection

This request creates a new VPN connection.

POST /vpn_gateways/{vpn_gateway_id}/connections
Request

Path Parameters

  • The VPN 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]

The VPN connection template.

Response

Status Code

  • The VPN connection was created successfully.

  • An invalid VPN connection template was provided.

Example responses

Delete a VPN connection

This request deletes a VPN connection. This operation cannot be reversed.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection 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 VPN connection deletion request has been accepted.

  • A VPN connection with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified VPN connection

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

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection 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 VPN connection was retrieved successfully.

  • A VPN connection with the specified identifier could not be found.

Example responses

Update a VPN connection

This request updates the properties of an existing VPN connection.

PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection 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 VPN connection patch.

Response

Status Code

  • The VPN connection was updated successfully.

  • An invalid VPN connection patch was provided.

  • A VPN connection with the specified identifier could not be found.

Example responses

List all local CIDRs for a resource

This request lists all local CIDRs for the resource specified by the identifier in the URL.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection 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 CIDRs were retrieved successfully.

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

Example responses

Remove a CIDR from a resource

This request removes a CIDR from a resource.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 CIDR was successfully removed from the resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Check if a specific CIDR exists on a specific resource

This request succeeds if a CIDR exists on the resource and fails otherwise.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 specified CIDR exists on the specified resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Set a CIDR on a resource

This request adds the specified CIDR to the specified resource. A request body is not required, and if supplied, is ignored. This request succeeds if the CIDR already exists on the resource.

PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 CIDR was successfully set on the resource.

  • The supplied CIDR was invalid.

  • The specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

List all peer CIDRs for a resource

This request lists all peer CIDRs for the resource specified by the identifier in the URL.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection 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 CIDRs were retrieved successfully.

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

Example responses

Remove a CIDR from a resource

This request removes a CIDR from a resource.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 CIDR was successfully removed from the resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Check if a specific CIDR exists on a specific resource

This request succeeds if a CIDR exists on the resource and fails otherwise.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 specified CIDR exists on the specified resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Set a CIDR on a resource

This request adds the specified CIDR to the specified resource. A request body is not required, and if supplied, is ignored. This request succeeds if the CIDR already exists on the resource.

PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

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 CIDR was successfully set on the resource.

  • The supplied CIDR was invalid.

  • The specified resource could not be found.

No Sample Response

This method does not specify any sample 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]

  • 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 resources within the VPC of the specified identifier

  • Filters the collection to resources within the VPC of the specified CRN

  • Filters the collection to resources within the VPC of the specified name

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