IBM Cloud API Docs

Introduction

This reference includes the full IBM Cloud® Virtual Private Cloud (VPC) Metadata API, as well as newly released open beta features. This reference may also include limited beta features for customer accounts with special approval to preview those features.

There are no backward-compatibility guarantees as a feature progresses through its beta phase, or from the final beta release to its initial GA release. Using features that are not GA mature could introduce the risk of corrupting resources in your account.

Access tokens and Certificates methods are no longer in this API reference. Those methods are now documeted in the Beta VPC Identity API.

Read the introduction in the generally available VPC Metadata API for details on endpoint URLs, auditing, error handling, versioning, and other important information.

Versioning

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.

This reference documents API behavior for any date value in the version parameter within 45 days of today’s date. To view the reference for any other supported versions of the API, select it from the Version list. See also Versioning in the VPC API.

Maturity query parameter

API requests accept a maturity query parameter. This parameter lets you decide on the level of stability to use before features become generally available.

API requests must specify a maturity=beta query parameter. Omitting maturity results in the GA version of the API being used, which can result in different behavior.

Example of using the maturity parameter in a request:

curl -X GET   "$vpc_metadata_api_endpoint/metadata/v1/instance?maturity=beta"   -H "Authorization: Bearer $iam_token"

Authentication

To start an authenticated session, create an identity access token. You can later generate an IAM access token by using an identity token and then use that token to access IAM-enabled services. For more information, see Configure the metadata service and the examples on this page.

A session lasts for the lifetime of the token, during which the metadata service can be called. You can reuse a single access token for multiple metadata API calls, as long as the token has not expired.

The examples use jq as a parser, a third-party tool licensed under the MIT license. jq may not come preinstalled on all VPC images available when creating an instance. You might need to install jq prior to use or use any parser of your choice.

Consider storing the metadata endpoint in a variable. Use the example on this page or see Configure the metadata service for more information.

This example extracts the access token value and places it in the identity_token environment variable.

identity_token=`curl -X PUT   "$vpc_metadata_api_endpoint/identity/v1/token?version=2025-07-15"   -H "Metadata-Flavor: ibm"   -H "Accept: application/json"   -d '{           "expires_in": 300       }' | jq -r '(.access_token)'`

Example response from the previous request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5MmI0YzAxNWJhOTc4NzgiLCJ....",
  "created_at": "2024-06-24T11:08:39.363Z",
  "expires_at": "2024-06-24T11:13:39.363Z",
  "expires_in": 300
}

Pass the access token in the Authorization header to authenticate metadata requests. Tokens authenticate requests without embedding service credentials in every call. See the methods in the API specification for examples using $identity_token.

This example uses the identity_token environment variable from the previous example to create an IAM token associated with the specified trusted profile ID. Upon success, provide the iam_token environment variable when calling any IAM-enabled IBM service to perform operations using the authorizations granted to that trusted profile. Learn more about Creating trusted profiles.

iam_token=`curl -X POST   "$vpc_metadata_api_endpoint/identity/v1/iam_token?version=2025-07-15"   -H "Authorization: Bearer $identity_token"   -d '{
       "trusted_profile": {
          "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
       }
      }' | jq -r '(.access_token)'`

This example shows how to use the HTTPS protocol to retrieve instance initialization metadata. For this example, the service must be configured with the metadata_service.protocol property set to https.

user_data=`curl -X GET    "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2025-07-15"   -H "Accept: application/json"   -H "Authorization: Bearer $identity_token"
  | jq -r '(.user_data)'`

Change log

Important changes to the beta metadata API, such as additions, updates, and deprecations, are documented in the Beta VPC Metadata API change log.

Methods

Retrieve the instance

This requests retrieves information for the calling instance.

GET /metadata/v1/instance

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance.read

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "availability_policy": {
        "host_failure": "restart"
      },
      "bandwidth": 4000,
      "boot_volume_attachment": {
        "device": {
          "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb"
        },
        "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
        "name": "my-volume-attachment",
        "volume": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
          "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
          "name": "my-volume",
          "resource_type": "volume"
        }
      },
      "cluster_network_attachments": [],
      "confidential_compute_mode": "sgx",
      "created_at": "2020-03-26T16:11:57Z",
      "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0",
      "dedicated_host": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "name": "my-dedicated-host",
        "resource_type": "dedicated_host"
      },
      "disks": [],
      "enable_secure_boot": true,
      "health_reasons": [],
      "health_state": "ok",
      "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0",
      "image": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
        "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
        "name": "my-image",
        "resource_type": "image"
      },
      "lifecycle_reasons": [],
      "lifecycle_state": "stable",
      "memory": 8,
      "metadata_service": {
        "enabled": true,
        "protocol": "http",
        "response_hop_limit": 1
      },
      "name": "my-instance",
      "network_attachments": [
        {
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-attachment",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip-z1",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "name": "my-virtual-network-interface",
            "resource_type": "virtual_network_interface"
          }
        }
      ],
      "network_interfaces": [
        {
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-interface",
          "primary_ipv4_address": "10.0.1.5",
          "resource_type": "network_interface",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          }
        }
      ],
      "numa_count": 2,
      "placement_target": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "name": "my-dedicated-host",
        "resource_type": "dedicated_host"
      },
      "primary_network_attachment": {
        "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
        "name": "my-instance-network-attachment",
        "primary_ip": {
          "address": "10.0.1.5",
          "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
          "name": "my-reserved-ip-z1",
          "resource_type": "subnet_reserved_ip"
        },
        "resource_type": "instance_network_attachment",
        "subnet": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "name": "my-subnet",
          "resource_type": "subnet"
        },
        "virtual_network_interface": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "name": "my-virtual-network-interface",
          "resource_type": "virtual_network_interface"
        }
      },
      "primary_network_interface": {
        "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
        "name": "my-instance-network-interface",
        "primary_ipv4_address": "10.0.1.5",
        "resource_type": "network_interface",
        "subnet": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "name": "my-subnet",
          "resource_type": "subnet"
        }
      },
      "profile": {
        "name": "bx2-4x16",
        "resource_type": "instance_profile"
      },
      "reservation_affinity": {
        "policy": "disabled",
        "pool": []
      },
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "instance",
      "startable": true,
      "status": "running",
      "status_reasons": [],
      "total_network_bandwidth": 3000,
      "total_volume_bandwidth": 1000,
      "vcpu": {
        "architecture": "amd64",
        "count": 56,
        "manufacturer": "intel"
      },
      "volume_attachments": [
        {
          "device": {
            "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb"
          },
          "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
          "name": "my-volume-attachment",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "name": "my-volume",
            "resource_type": "volume"
          }
        },
        {
          "device": {
            "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8"
          },
          "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70",
          "name": "my-volume-attachment-2",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392",
            "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392",
            "name": "my-volume-2",
            "resource_type": "volume"
          }
        }
      ],
      "vpc": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "name": "my-vpc",
        "resource_type": "vpc"
      },
      "zone": {
        "name": "us-south-1"
      }
    }

List cluster network attachments

This request lists cluster network attachments for the calling instance.

GET /metadata/v1/instance/cluster_network_attachments

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-cluster-network-attachment.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

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

    Possible values: 1 ≤ length ≤ 4096, Value must match regular expression ^[ -~]+$

  • The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/cluster_network_attachments?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance cluster network attachments were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "cluster_network_attachments": [
        {
          "before": {
            "id": "0717-a69563fa-0415-4d6e-aeb3-a3f14654bf90",
            "name": "other-instance-cluster-network-attachment",
            "resource_type": "instance_cluster_network_attachment"
          },
          "cluster_network_interface": {
            "id": "0717-ffc092f7-5d02-4b93-ab69-26860529b9fb",
            "name": "my-cluster-network-interface",
            "primary_ip": {
              "address": "10.1.0.6",
              "id": "0717-d4d6489a-3bf5-4104-a33a-3572faf2d117",
              "name": "my-cluster-network-subnet-reserved-ip",
              "resource_type": "cluster_network_subnet_reserved_ip"
            },
            "resource_type": "cluster_network_interface",
            "subnet": {
              "id": "0717-7931845c-65c4-4b0a-80cd-7d9c1a6d7930",
              "name": "my-cluster-network-subnet",
              "resource_type": "cluster_network_subnet"
            }
          },
          "id": "0717-fb880975-db45-4459-8548-64e3995ac213",
          "lifecycle_reasons": [],
          "lifecycle_state": "stable",
          "name": "my-instance-cluster-network-attachment",
          "resource_type": "instance_cluster_network_attachment"
        }
      ],
      "first": {
        "href": "https://api.metadata.cloud.ibm.com/metadata/v1/instance/cluster_network_attachments?limit=20"
      },
      "limit": 20,
      "total_count": 1
    }

Retrieve a cluster network attachment

This request retrieves a cluster network attachment for the calling instance.

GET /metadata/v1/instance/cluster_network_attachments/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-cluster-network-attachment.read

Request

Path Parameters

  • The instance cluster network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/cluster_network_attachments/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance cluster network attachment was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A cluster network attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "before": {
        "id": "0717-a69563fa-0415-4d6e-aeb3-a3f14654bf90",
        "name": "other-instance-cluster-network-attachment",
        "resource_type": "instance_cluster_network_attachment"
      },
      "cluster_network_interface": {
        "id": "0717-ffc092f7-5d02-4b93-ab69-26860529b9fb",
        "name": "my-cluster-network-interface",
        "primary_ip": {
          "address": "10.1.0.6",
          "id": "0717-d4d6489a-3bf5-4104-a33a-3572faf2d117",
          "name": "my-cluster-network-subnet-reserved-ip",
          "resource_type": "cluster_network_subnet_reserved_ip"
        },
        "resource_type": "cluster_network_interface",
        "subnet": {
          "id": "0717-7931845c-65c4-4b0a-80cd-7d9c1a6d7930",
          "name": "my-cluster-network-subnet",
          "resource_type": "cluster_network_subnet"
        }
      },
      "id": "0717-fb880975-db45-4459-8548-64e3995ac213",
      "lifecycle_reasons": [],
      "lifecycle_state": "stable",
      "name": "my-instance-cluster-network-attachment",
      "resource_type": "instance_cluster_network_attachment"
    }

Retrieve initialization information

This request retrieves initialization information for the calling instance.

GET /metadata/v1/instance/initialization

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-initialization.read

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The initialization information was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "default_trusted_profile": {
        "auto_link": true,
        "target": {
          "crn": "crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5",
          "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5",
          "resource_type": "trusted_profile"
        }
      },
      "keys": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
          "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "name": "my-key-1"
        }
      ],
      "user_data": "[...]"
    }

List network attachments

This request lists network attachments for the calling instance.

GET /metadata/v1/instance/network_attachments

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-attachment.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance network attachments were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "network_attachments": [
        {
          "created_at": "2023-09-30T23:42:32.993Z",
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "lifecycle_state": "stable",
          "name": "my-instance-network-attachment",
          "port_speed": 1000,
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip-z1",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "type": "primary",
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "name": "my-virtual-network-interface",
            "resource_type": "virtual_network_interface"
          }
        },
        {
          "created_at": "2023-09-30T23:42:33.366Z",
          "id": "0717-822a3789-61d5-4b8e-82c5-4310e6b7dc1b",
          "lifecycle_state": "stable",
          "name": "my-instance-network-attachment-2",
          "port_speed": 1000,
          "primary_ip": {
            "address": "10.0.2.10",
            "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749",
            "name": "my-reserved-ip-z1-2",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "name": "my-subnet-z1-2",
            "resource_type": "subnet"
          },
          "type": "secondary",
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
            "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
            "name": "my-virtual-network-interface-2",
            "resource_type": "virtual_network_interface"
          }
        }
      ]
    }

Retrieve a network attachment

This request retrieves a network attachment for the calling instance.

GET /metadata/v1/instance/network_attachments/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-attachment.read

Request

Path Parameters

  • The instance network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance network attachment was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A network attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2023-09-30T23:42:32.993Z",
      "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
      "lifecycle_state": "stable",
      "name": "my-instance-network-attachment",
      "port_speed": 1000,
      "primary_ip": {
        "address": "10.0.1.5",
        "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
        "name": "my-reserved-ip-z1",
        "resource_type": "subnet_reserved_ip"
      },
      "resource_type": "instance_network_attachment",
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary",
      "virtual_network_interface": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
        "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
        "name": "my-virtual-network-interface",
        "resource_type": "virtual_network_interface"
      }
    }

List instance network interfaces

This request lists network interfaces for the calling instance.

GET /metadata/v1/instance/network_interfaces

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-interface.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance network interfaces were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "network_interfaces": [
        {
          "allow_ip_spoofing": false,
          "created_at": "2024-10-15T03:24:32.993Z",
          "floating_ips": [
            {
              "address": "203.0.113.1",
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
              "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
              "name": "my-floating-ip"
            }
          ],
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-interface",
          "port_speed": 1000,
          "primary_ipv4_address": "10.0.1.5",
          "resource_type": "network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "status": "available",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "type": "primary"
        }
      ]
    }

Retrieve an instance network interface

This request retrieves a network interface for the calling instance.

GET /metadata/v1/instance/network_interfaces/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-interface.read

Request

Path Parameters

  • The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The instance network interface was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • An instance network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "allow_ip_spoofing": false,
      "created_at": "2024-10-15T03:24:32.993Z",
      "floating_ips": [
        {
          "address": "203.0.113.1",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
          "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
          "name": "my-floating-ip"
        }
      ],
      "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
      "name": "my-instance-network-interface",
      "port_speed": 1000,
      "primary_ipv4_address": "10.0.1.5",
      "resource_type": "network_interface",
      "security_groups": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "name": "my-security-group"
        }
      ],
      "status": "available",
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary"
    }

List volume attachments

This request lists volume attachments for the calling instance.

GET /metadata/v1/instance/volume_attachments

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-volume-attachment.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The volume attachments were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "volume_attachments": [
        {
          "bandwidth": 250,
          "created_at": "2024-10-24T16:32:05.000Z",
          "delete_volume_on_instance_delete": true,
          "device": {
            "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8"
          },
          "id": "0717-fdb3642d-c849-4c29-97a9-03b868616f88",
          "name": "my-boot-volume-attachment",
          "status": "attached",
          "type": "boot",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-89b05e9a-e635-9464-9747-7ae3f9b03303",
            "id": "r006-89b05e9a-e635-9464-9747-7ae3f9b03303",
            "name": "my-boot-volume",
            "resource_type": "volume"
          }
        },
        {
          "bandwidth": 250,
          "created_at": "2019-03-15T11:44:07.000Z",
          "delete_volume_on_instance_delete": false,
          "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
          "name": "my-data-volume-attachment",
          "status": "attached",
          "type": "data",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "name": "my-volume",
            "resource_type": "volume"
          }
        }
      ]
    }

Retrieve a volume attachment

This request retrieves a volume attachment for the calling instance.

GET /metadata/v1/instance/volume_attachments/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-volume-attachment.read

Request

Path Parameters

  • The volume attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The volume attachment was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A volume attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "bandwidth": 250,
      "created_at": "2019-03-15T11:44:07.000Z",
      "delete_volume_on_instance_delete": false,
      "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
      "name": "my-data-volume-attachment",
      "status": "attached",
      "type": "data",
      "volume": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
        "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
        "name": "my-volume",
        "resource_type": "volume"
      }
    }

List public SSH keys

This request lists public SSH keys

GET /metadata/v1/keys

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-key.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The keys were retrieved successfully

Example responses
  • {
      "keys": [
        {
          "created_at": "2019-01-29T03:48:11.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
          "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "length": 2048,
          "name": "my-key-1",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "type": "rsa"
        },
        {
          "created_at": "2024-10-01T21:46:21.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468",
          "fingerprint": "SHA256:XgUFJWiZbPehNHl706+mJbZdPDmSJh8G2ycvCYR2t5U",
          "id": "r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468",
          "length": 2048,
          "name": "my-key-2",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6iw94c1htpVzC33sd874W6SeTZ9pGDZdY50vsnPUpYVfuU9WDscyy/NYVR74ZvSw1vN1QK57GEW46Uhh2JdvyQ1jiMPI6amu6bHiBqnWTo3HUFPBoxM9/3j0MhspjGyrO7JK3fOwyGrnquAqRq5BPibN8JLuZwCfVyucz98hEmnf9sEphJ5ab3ywVU3echaJZBEdUNEf2ZAHGGe5qnVW33y4PmRf5q90mPkJYwjTgTjZ3fPG2lV01S3eTbHV7zr1wxW4FSTFm7dVnfTURPzKc7mL4MS35s9gX73imvZL6O9ZH54IDoB8TBhx0U5657n6MoznFeXVcFSDLLpMXf7Gr",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "type": "rsa"
        }
      ]
    }

Retrieve a public SSH key

This request retrieves a public SSH key

GET /metadata/v1/keys/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-key.read

Request

Path Parameters

  • The key identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The key was retrieved successfully

  • A key with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2019-01-29T03:48:11.000Z",
      "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
      "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
      "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
      "length": 2048,
      "name": "my-key-1",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "type": "rsa"
    }

List placement groups

This request lists placement groups.

GET /metadata/v1/placement_groups

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-placement-group.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The placement groups were retrieved successfully

Example responses
  • {
      "placement_groups": [
        {
          "created_at": "2020-12-29T19:55:00.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
          "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
          "lifecycle_state": "stable",
          "name": "my-placement-group",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "placement_group",
          "strategy": "host_spread"
        }
      ]
    }

Retrieve a placement group

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

GET /metadata/v1/placement_groups/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-placement-group.read

Request

Path Parameters

  • The placement group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The placement group was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A placement group with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2020-12-29T19:55:00.000Z",
      "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "lifecycle_state": "stable",
      "name": "my-placement-group",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "placement_group",
      "strategy": "host_spread"
    }

List virtual network interfaces

This request lists virtual network interfaces targeting the calling instance

GET /metadata/v1/virtual_network_interfaces

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-virtual-network-interface.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The virtual network interfaces were retrieved successfully

Example responses
  • {
      "virtual_network_interfaces": [
        {
          "allow_ip_spoofing": false,
          "auto_delete": true,
          "created_at": "2024-10-15T03:24:32.993Z",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "enable_infrastructure_nat": false,
          "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "ips": [
            {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip-z1",
              "resource_type": "subnet_reserved_ip"
            }
          ],
          "lifecycle_state": "stable",
          "mac_address": "02:00:04:00:C4:6A",
          "name": "my-virtual-network-interface",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip-z1",
            "resource_type": "subnet_reserved_ip"
          },
          "protocol_state_filtering_mode": "auto",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "virtual_network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "target": {
            "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
            "name": "my-instance-network-attachment",
            "primary_ip": {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip-z1",
              "resource_type": "subnet_reserved_ip"
            },
            "resource_type": "instance_network_attachment",
            "subnet": {
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
              "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
              "name": "my-subnet",
              "resource_type": "subnet"
            },
            "virtual_network_interface": {
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
              "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
              "name": "my-virtual-network-interface",
              "resource_type": "virtual_network_interface"
            }
          },
          "vpc": {
            "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "name": "my-vpc",
            "resource_type": "vpc"
          },
          "zone": {
            "name": "us-south-1"
          }
        },
        {
          "allow_ip_spoofing": false,
          "auto_delete": true,
          "created_at": "2024-10-23T03:23:32.993Z",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
          "enable_infrastructure_nat": false,
          "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
          "ips": [
            {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip-z1",
              "resource_type": "subnet_reserved_ip"
            },
            {
              "address": "10.0.2.10",
              "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749",
              "name": "my-reserved-ip-z1-2",
              "resource_type": "subnet_reserved_ip"
            }
          ],
          "lifecycle_state": "stable",
          "mac_address": "02:00:04:00:C4:6B",
          "name": "my-virtual-network-interface-2",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip-z1",
            "resource_type": "subnet_reserved_ip"
          },
          "protocol_state_filtering_mode": "auto",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "virtual_network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "ipv4_cidr_block": "10.0.2.0/24",
            "name": "my-subnet-z1-2",
            "resource_type": "subnet"
          },
          "target": {
            "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
            "name": "my-instance-network-attachment",
            "primary_ip": {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip-z1",
              "resource_type": "subnet_reserved_ip"
            },
            "resource_type": "instance_network_attachment",
            "subnet": {
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
              "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
              "name": "my-subnet",
              "resource_type": "subnet"
            },
            "virtual_network_interface": {
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
              "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
              "name": "my-virtual-network-interface",
              "resource_type": "virtual_network_interface"
            }
          },
          "vpc": {
            "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "name": "my-vpc",
            "resource_type": "vpc"
          },
          "zone": {
            "name": "us-south-1"
          }
        }
      ]
    }

Retrieve a virtual network interface

This request retrieves a virtual network interface targeting the calling instance.

GET /metadata/v1/virtual_network_interfaces/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-virtual-network-interface.read

Request

Path Parameters

  • The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-07-15 and 2025-07-15.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces/$id?version=2025-07-15&maturity=beta" -H "Authorization: Bearer $identity_token"

Response

Status Code

  • The virtual network interface was retrieved successfully

  • A virtual network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "allow_ip_spoofing": false,
      "auto_delete": true,
      "created_at": "2024-10-15T03:24:32.993Z",
      "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
      "enable_infrastructure_nat": false,
      "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
      "ips": [
        {
          "address": "10.0.1.5",
          "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
          "name": "my-reserved-ip-z1",
          "resource_type": "subnet_reserved_ip"
        }
      ],
      "lifecycle_state": "stable",
      "mac_address": "02:00:04:00:C4:6A",
      "name": "my-virtual-network-interface",
      "primary_ip": {
        "address": "10.0.1.5",
        "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
        "name": "my-reserved-ip-z1",
        "resource_type": "subnet_reserved_ip"
      },
      "protocol_state_filtering_mode": "auto",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "virtual_network_interface",
      "security_groups": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "name": "my-security-group"
        }
      ],
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "target": {
        "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
        "name": "my-instance-network-attachment",
        "primary_ip": {
          "address": "10.0.1.5",
          "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
          "name": "my-reserved-ip-z1",
          "resource_type": "subnet_reserved_ip"
        },
        "resource_type": "instance_network_attachment",
        "subnet": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "name": "my-subnet",
          "resource_type": "subnet"
        },
        "virtual_network_interface": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "name": "my-virtual-network-interface",
          "resource_type": "virtual_network_interface"
        }
      },
      "vpc": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "name": "my-vpc",
        "resource_type": "vpc"
      },
      "zone": {
        "name": "us-south-1"
      }
    }
id=curlclassName=tab-item-selected