IBM Cloud Docs
Updating to the 2025-06-30 version (image ownership property and filter change)

Updating to the 2025-06-30 version (image ownership property and filter change)

As described in the VPC API reference versioning policy, most changes to the VPC APIs are fully backward compatible and are made available to all clients, regardless of the API version the client requests. However, the 2025-06-30 release of the VPC API necessitated incompatible changes in support of improved modeling of the ownership property of image resources.

Before you adopt the release version 2025-06-30 or later, review the changes described in this migration guidance that might require you to update your client.

Changed image properties

The following properties have changed for API requests that use a version query parameter of 2025-06-30 or later.

When retrieving, listing, creating, or updating images, the following resulting properties have changed for API requests that use a version query parameter of 2025-06-30 or later.

Old and new properties resulting when retrieving, listing, creating, or updating images.
Old property New property
owner_type remote.account

When listing images, the following query parameters have changed for API requests that use a version query parameter of 2025-06-30 or later.

Old and new query parameters when retrieving images.
Old parameter New parameter
owner_type remote.account.id

Action needed

Before you specify the version query parameter of 2025-06-30 or later, follow these actions to avoid regressions in client functionality.

If your clients continue to specify version 2025-06-29 or earlier, no changes are required.

Client migration

Before you migrate a client to API version 2025-06-30 or later, review your code that uses the following methods:

  • POST /images
  • GET /images/{id}
  • GET /images
  • PATCH /images/{id}

Review the changes that were announced in the API change log, and verify that your code adopts these changes in a manner that is appropriate for your programming language.

Examples

These examples compare differences between before and after the 2025-06-30 versioned change.

Properties of images owned by the requesting account

The following example image is from a response to a request made using API version 2025-06-29 or earlier. The image is owned by the requesting account, so it includes the owner_type property set to user.

curl -X GET "$vpc_api_endpoint/v1/images/$image_id?version=2025-06-29&generation=2" -H "Authorization: $iam_token"
{
  "id": "r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "crn": "crn:v1:bluemix:public:is:us-south:a/3f728115e2294567898f7212ed0b1418::image:r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "name": "my-image",
  "minimum_provisioned_size": 100,
  "resource_group": {
    "id": "111fdd0ccab94cdeb0ef8a41183e132a",
    "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/111fdd0ccab94cdeb0ef8a41183e132a",
    "name": "Default"
  },
  "created_at": "2025-05-28T10:00:14Z",
  "file": {
    "checksums": {
      "sha256": "ff3c40900eb47230a89533c5feb4e090c6328b7b41b308b64242cab475b60121"
    },
    "size": 2
  },
  "operating_system": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
    "name": "red-8-amd64",
    "architecture": "amd64",
    "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
    "family": "Red Hat Enterprise Linux",
    "vendor": "Red Hat",
    "version": "8.x - Minimal Install",
    "dedicated_host_only": false,
    "allow_user_image_creation": true,
    "user_data_format": "cloud_init"
  },
  "status": "available",
  "visibility": "private",
  "encryption": "none",
  "status_reasons": [],
  "owner_type": "user",
  "catalog_offering": {
    "managed": false
  },
  "resource_type": "image",
  "user_data_format": "cloud_init",
  "allowed_use": {
    "instance": "true",
    "bare_metal_server": "true",
    "api_version": "2025-05-15"
  }
}

The following example image is from a response to a request made using API version 2025-06-30 or later. The image is owned by the requesting account, so it omits remote.account because the owning account is not remote.

curl -X GET "$vpc_api_endpoint/v1/images/$image_id?version=2025-06-30&generation=2" -H "Authorization: $iam_token"
{
  "id": "r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "crn": "crn:v1:bluemix:public:is:us-south:a/3f728115e2294567898f7212ed0b1418::image:r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
  "name": "my-image",
  "minimum_provisioned_size": 100,
  "resource_group": {
    "id": "111fdd07fab94cdeb0ef8a47b83e132a",
    "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/111fdd0ccab94cdeb0ef8a47b83e132a",
    "name": "Default"
  },
  "created_at": "2025-05-28T10:00:14Z",
  "file": {
    "checksums": {
      "sha256": "ff3c40900eb47230a89533c5feb4e090c6328b7b41b308b64242cab475b60121"
    },
    "size": 2
  },
  "operating_system": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
    "name": "red-8-amd64",
    "architecture": "amd64",
    "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
    "family": "Red Hat Enterprise Linux",
    "vendor": "Red Hat",
    "version": "8.x - Minimal Install",
    "dedicated_host_only": false,
    "allow_user_image_creation": true,
    "user_data_format": "cloud_init"
  },
  "status": "available",
  "visibility": "private",
  "encryption": "none",
  "status_reasons": [],
  "catalog_offering": {
    "managed": false
  },
  "resource_type": "image",
  "user_data_format": "cloud_init",
  "allowed_use": {
    "instance": "true",
    "bare_metal_server": "true",
    "api_version": "2025-05-15"
  }
}

Properties of images not owned by the requesting account

The following example image is from a response to a request made using API version 2025-06-29 or earlier. The image is not owned by the requesting account, so it includes the owner_type property set to provider.

curl -X GET "$vpc_api_endpoint/v1/images/$image_id?version=2025-06-29&generation=2" -H "Authorization: $iam_token"
{
  "id": "r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "crn": "crn:v1:bluemix:public:is:us-south:a/811f8abfbd32425597dc7ba40da98fa6::image:r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "name": "ibm-redhat-8-8-minimal-amd64-10",
  "minimum_provisioned_size": 100,
  "resource_group": {
    "id": "4cdc4448a0a148159685b9b0dc54ed19",
    "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/4cdc4448a0a148159685b9b0dc54ed19",
    "name": "Default"
  },
  "created_at": "2025-04-11T04:35:45Z",
  "file": {
    "checksums": {
      "sha256": "5c356e409f6fea99afd93477c1c54a78e118e454c993874339884e9096978fe5"
    },
    "size": 2
  },
  "operating_system": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
    "name": "red-8-amd64",
    "architecture": "amd64",
    "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
    "family": "Red Hat Enterprise Linux",
    "vendor": "Red Hat",
    "version": "8.x - Minimal Install",
    "dedicated_host_only": false,
    "allow_user_image_creation": true,
    "user_data_format": "cloud_init"
  },
  "status": "available",
  "visibility": "public",
  "encryption": "none",
  "status_reasons": [],
  "owner_type": "provider",
  "catalog_offering": {
    "managed": false
  },
  "resource_type": "image",
  "user_data_format": "cloud_init",
  "allowed_use": {
    "instance": "true",
    "bare_metal_server": "true",
    "api_version": "2025-04-11"
  }
}

The following example image is from a response to a request made using API version 2025-06-30 or later. The image is not owned by the requesting account, so it includes the remote.account property with remote.account.id set to the account identifier of the image owner.

curl -X GET "$vpc_api_endpoint/v1/images/$image_id?version=2025-06-30&generation=2" -H "Authorization: $iam_token"
{
  "id": "r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "crn": "crn:v1:bluemix:public:is:us-south:a/811f8abfbd32425597dc7ba40da98fa6::image:r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
  "name": "ibm-redhat-8-8-minimal-amd64-10",
  "minimum_provisioned_size": 100,
  "resource_group": {
    "id": "4cdc4448a0a148159685b9b0dc549d19",
    "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/4cdc4448a0a148159685b9b0dc549d19",
    "name": "Default"
  },
  "created_at": "2025-04-11T04:35:45Z",
  "file": {
    "checksums": {
      "sha256": "5c356e455f6fea99afd93477c1c54a78e118e454c993874339884e9096978fe5"
    },
    "size": 2
  },
  "operating_system": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
    "name": "red-8-amd64",
    "architecture": "amd64",
    "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
    "family": "Red Hat Enterprise Linux",
    "vendor": "Red Hat",
    "version": "8.x - Minimal Install",
    "dedicated_host_only": false,
    "allow_user_image_creation": true,
    "user_data_format": "cloud_init"
  },
  "status": "available",
  "visibility": "public",
  "encryption": "none",
  "status_reasons": [],
  "catalog_offering": {
    "managed": false
  },
  "resource_type": "image",
  "user_data_format": "cloud_init",
  "allowed_use": {
    "instance": "true",
    "bare_metal_server": "true",
    "api_version": "2025-04-11"
  },
  "remote": {
    "account": {
      "id": "811f8abfbd32425597dc7ba40da98fa6",
      "resource_type": "image"
    }
  }
}

Listing images owned by the requesting account

The following example uses API version 2025-06-29 or earlier and query parameter owner_type=user to list images owned by the requesting account.

curl -X GET "$vpc_api_endpoint/v1/images?version=2025-06-29&generation=2&owner_type=user" -H "Authorization: $iam_token"

The response includes only images with owner_type set to user:

{
  "first": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50"
  },
  "limit": 50,
  "total_count": 1,
  "images": [
    {
      "id": "r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "crn": "crn:v1:bluemix:public:is:us-south:a/3f728115e2294567898f7212ed0b1418::image:r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "name": "my-image",
      "minimum_provisioned_size": 100,
      "resource_group": {
        "id": "111fdd07fab94cdeb0ef8a47b83e132a",
        "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/111fdd0ccab94cdeb0ef8a47b83e132a",
        "name": "Default"
      },
      "created_at": "2025-05-28T10:00:14Z",
      "file": {
        "checksums": {
          "sha256": "ff3c40900eb47230a89533c5feb4e090c6328b7b41b308b64242cab475b60121"
        },
        "size": 2
      },
      "operating_system": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
        "name": "red-8-amd64",
        "architecture": "amd64",
        "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
        "family": "Red Hat Enterprise Linux",
        "vendor": "Red Hat",
        "version": "8.x - Minimal Install",
        "dedicated_host_only": false,
        "allow_user_image_creation": true,
        "user_data_format": "cloud_init"
      },
      "status": "available",
      "visibility": "private",
      "encryption": "none",
      "status_reasons": [],
      "owner_type": "user",
      "catalog_offering": {
        "managed": false
      },
      "resource_type": "image",
      "user_data_format": "cloud_init",
      "allowed_use": {
        "instance": "true",
        "bare_metal_server": "true",
        "api_version": "2025-05-15"
      }
    }
  ]
}

The following example uses API version 2025-06-30 or later and query parameter remote.account.id=null to list images owned by the requesting account.

curl -X GET "$vpc_api_endpoint/v1/images?version=2025-06-30&generation=2&remote.account.id=null" -H "Authorization: $iam_token"

The response includes only images without remote.account set because the owning account is not remote:

{
  "first": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50"
  },
  "limit": 50,
  "total_count": 1,
  "images": [
    {
      "id": "r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "crn": "crn:v1:bluemix:public:is:us-south:a/3f728115e2294567898f7212ed0b1418::image:r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-426418bb-a89c-42fa-9ece-ac2d1b73ebe6",
      "name": "my-image",
      "minimum_provisioned_size": 100,
      "resource_group": {
        "id": "111fdd07fab94cdeb0ef8a47b83e132a",
        "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/111fdd0ccab94cdeb0ef8a47b83e132a",
        "name": "Default"
      },
      "created_at": "2025-05-28T10:00:14Z",
      "file": {
        "checksums": {
          "sha256": "ff3c40900eb47230a89533c5feb4e090c6328b7b41b308b64242cab475b60121"
        },
        "size": 2
      },
      "operating_system": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
        "name": "red-8-amd64",
        "architecture": "amd64",
        "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
        "family": "Red Hat Enterprise Linux",
        "vendor": "Red Hat",
        "version": "8.x - Minimal Install",
        "dedicated_host_only": false,
        "allow_user_image_creation": true,
        "user_data_format": "cloud_init"
      },
      "status": "available",
      "visibility": "private",
      "encryption": "none",
      "status_reasons": [],
      "catalog_offering": {
        "managed": false
      },
      "resource_type": "image",
      "user_data_format": "cloud_init",
      "allowed_use": {
        "instance": "true",
        "bare_metal_server": "true",
        "api_version": "2025-05-15"
      }
    }
  ]
}

Listing images not owned by the requesting account

The following example uses API version 2025-06-29 or earlier and query parameter owner_type=provider to list images not owned by the requesting account.

curl -X GET "$vpc_api_endpoint/v1/images?version=2025-06-29&generation=2&owner_type=provider" -H "Authorization: $iam_token"

The response includes only images with owner_type set to provider:

{
  "first": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50"
  },
  "limit": 50,
  "total_count": 1,
  "images": [
    {
      "id": "r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "crn": "crn:v1:bluemix:public:is:us-south:a/811f8abfbd32425597dc7ba40da98fa6::image:r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "name": "ibm-redhat-8-8-minimal-amd64-10",
      "minimum_provisioned_size": 100,
      "resource_group": {
        "id": "4cdc4448a0a148159685b9b0dc54ed19",
        "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/4cdc4448a0a148159685b9b0dc54ed19",
        "name": "Default"
      },
      "created_at": "2025-04-11T04:35:45Z",
      "file": {
        "checksums": {
          "sha256": "5c356e409f6fea99afd93477c1c54a78e118e454c993874339884e9096978fe5"
        },
        "size": 2
      },
      "operating_system": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
        "name": "red-8-amd64",
        "architecture": "amd64",
        "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
        "family": "Red Hat Enterprise Linux",
        "vendor": "Red Hat",
        "version": "8.x - Minimal Install",
        "dedicated_host_only": false,
        "allow_user_image_creation": true,
        "user_data_format": "cloud_init"
      },
      "status": "available",
      "visibility": "public",
      "encryption": "none",
      "status_reasons": [],
      "owner_type": "provider",
      "catalog_offering": {
        "managed": false
      },
      "resource_type": "image",
      "user_data_format": "cloud_init",
      "allowed_use": {
        "instance": "true",
        "bare_metal_server": "true",
        "api_version": "2025-04-11"
      }
    }
  ]
}

The following example uses API version 2025-06-30 or later and query parameter remote.account.id=not:null to list images not owned by the requesting account.

curl -X GET "$vpc_api_endpoint/v1/images?version=2025-06-30&generation=2&remote.account.id=not:null" -H "Authorization: $iam_token"

The response includes only images with remote.account.id set because the owning account is remote:

{
  "first": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50"
  },
  "limit": 50,
  "total_count": 1,
  "images": [
    {
      "id": "r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "crn": "crn:v1:bluemix:public:is:us-south:a/811f8abfbd32425597dc7ba40da98fa6::image:r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-6795c5a0-d10f-4a89-aa93-a911e90f6cb8",
      "name": "ibm-redhat-8-8-minimal-amd64-10",
      "minimum_provisioned_size": 100,
      "resource_group": {
        "id": "4cdc4448a0a148159685b9b0dc549d19",
        "href": "https://resource-controller.cloud.ibm.com/v1/resource_groups/4cdc4448a0a148159685b9b0dc549d19",
        "name": "Default"
      },
      "created_at": "2025-04-11T04:35:45Z",
      "file": {
        "checksums": {
          "sha256": "5c356e455f6fea99afd93477c1c54a78e118e454c993874339884e9096978fe5"
        },
        "size": 2
      },
      "operating_system": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-8-amd64",
        "name": "red-8-amd64",
        "architecture": "amd64",
        "display_name": "Red Hat Enterprise Linux 8.x - Minimal Install (amd64)",
        "family": "Red Hat Enterprise Linux",
        "vendor": "Red Hat",
        "version": "8.x - Minimal Install",
        "dedicated_host_only": false,
        "allow_user_image_creation": true,
        "user_data_format": "cloud_init"
      },
      "status": "available",
      "visibility": "public",
      "encryption": "none",
      "status_reasons": [],
      "catalog_offering": {
        "managed": false
      },
      "resource_type": "image",
      "user_data_format": "cloud_init",
      "allowed_use": {
        "instance": "true",
        "bare_metal_server": "true",
        "api_version": "2025-04-11"
      },
      "remote": {
        "account": {
          "id": "811f8abfbd32425597dc7ba40da98fa6",
          "resource_type": "image"
        }
      }
    }
  ]
}