Get authorization options

GET /api/v1/auth

Get authorization options for the targeted account.

Request

Path Parameters

Query Parameters

Response

200 - Success

iam_authz

boolean

Enable role based authorization when authenticating with IBM Cloud IAM

private_only

boolean

Restrict account to only be able to push and pull images over private connections

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Update authorization options

PATCH /api/v1/auth

Update authorization options for the targeted account.

Request

Request Body

AuthOptions

A JSON document containing the requested updates.

iam_authz

boolean

Enable role based authorization when authenticating with IBM Cloud IAM

private_only

boolean

Restrict account to only be able to push and pull images over private connections

Path Parameters

Query Parameters

Response

204 - Success

400 - A required header is missing or invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to perform the requested operation. You must have either Manager or Billing Manager roles on the targeted account to perform this action.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get account settings

GET /api/v1/settings

Get account settings for the targeted account.

Request

Path Parameters

Query Parameters

Response

200 - Success

platform_metrics

boolean

Opt in to IBM Cloud Container Registry publishing platform metrics

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Update account settings

PATCH /api/v1/settings

Update settings for the targeted account.

Request

Request Body

AccountSettings

A JSON document containing the requested updates.

platform_metrics

boolean

Opt in to IBM Cloud Container Registry publishing platform metrics

Path Parameters

Query Parameters

Response

204 - Success

400 - A required header is missing or invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to perform the requested operation. You must have either Manager or Billing Manager roles on the targeted account to perform this action.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

List images

GET /api/v1/images

List all images in namespaces in a targeted IBM Cloud account.

Request

Path Parameters

Query Parameters

namespace

string

Lists images that are stored in the specified namespace only. Query multiple namespaces by specifying this option for each namespace. If this option is not specified, images from all namespaces in the specified IBM Cloud account are listed.

includeIBM

boolean

Includes IBM-provided public images in the list of images. If this option is not specified, private images are listed only. If this option is specified more than once, the last parsed setting is the setting that is used.

includePrivate

boolean

Includes private images in the list of images. If this option is not specified, private images are listed. If this option is specified more than once, the last parsed setting is the setting that is used.

includeManifestLists

boolean

Includes tags that reference multi-architecture manifest lists in the image list. If this option is not specified, tagged manifest lists are not shown in the list. If this option is specified more than once, the last parsed setting is the setting that is used.

vulnerabilities

boolean

Displays Vulnerability Advisor status for the listed images. If this option is specified more than once, the last parsed setting is the setting that is used.

repository

string

Lists images that are stored in the specified repository, under your namespaces. Query multiple repositories by specifying this option for each repository. If this option is not specified, images from all repos are listed.

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to the specified namespace. Choose another namespace.

code

string

message

string

rc

integer

request-id

string

404 - No namespaces were found for the targeted account. Add a namespace or target a different account. Alternatively, specify the option to include IBM-provided public images.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Bulk delete images

POST /api/v1/images/bulkdelete

Remove multiple container images from the registry.

Request

Request Body

bulkDeleteInput

The full IBM Cloud registry path to the images that you want to delete, including its digest. All tags for the supplied digest are removed.

Path Parameters

Query Parameters

Response

200 - Success

error

object

A map of digests to the error object that explains the failure.

success

array

A list of digests which were deleted successfully.

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

List images by digest

POST /api/v1/images/digests

List all images by digest in namespaces in a targeted IBM Cloud account.

Request

Request Body

ListImageDigestOptions

A JSON document containing the list options.

exclude_tagged

boolean

ExcludeTagged returns only untagged digests

exclude_va

boolean

ExcludeVA returns the digest list with no VA scan results

include_ibm

boolean

When true, API will return the IBM public images if they exist in the targeted region.

repositories

array

Repositories in which to restrict the output. If left empty all images for the account will be returned.

Path Parameters

Query Parameters

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to the specified namespace. Choose another namespace.

code

string

message

string

rc

integer

request-id

string

404 - No namespaces were found for the targeted account. Add a namespace or target a different account. Alternatively, specify the option to include IBM-provided public images.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Create tag

POST /api/v1/images/tags

Create a new tag in a private registry that refers to an existing image in the same region. If the fromimage has Red Hat® signatures and the toimage is in a different repository, those signatures are copied to that repository.

Request

Path Parameters

Query Parameters

fromimage

Required *

string

The name of the image that you want to create a new tag for, in the format <REPOSITORY>:<TAG>. Run `ibmcloud cr images` or call the `GET /images/json` endpoint to review images that are in the registry.

toimage

Required *

string

The new tag for the image, in the format <REPOSITORY>:<TAG>.

Response

201 - Success

400 - There was a problem with the input. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have authorization to access the specified namespace.

code

string

message

string

rc

integer

request-id

string

500 -

Delete image

DELETE /api/v1/images/{image}

Delete a container image from the registry.

Request

Path Parameters

image

Required *

string

The full IBM Cloud registry path to the image that you want to delete, including its tag. If you do not provide a specific tag, the version with the `latest` tag is removed.

Query Parameters

Response

200 - Success

Untagged

string

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have authorization to access the specified namespace.

code

string

message

string

rc

integer

request-id

string

404 - The specified image was not found. Check the spelling of the specified image.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Inspect an image

GET /api/v1/images/{image}/json

Inspect a container image in the private registry.

Request

Path Parameters

image

Required *

string

The full IBM Cloud registry path to the image that you want to inspect. Run `ibmcloud cr images` or call the `GET /images/json` endpoint to review images that are in the registry.

Query Parameters

Response

200 - Success

Architecture

string

The processor architecture used to build this image, and required to run it

Author

string

The author of the image

Comment

string

A plain text description of the image

Config

The configuration data about a container.

Container

string

The ID of the container which created this image

ContainerConfig

Config

The configuration data about a container.

Created

string

The unix timestamp for the date when the image was created

DockerVersion

string

The Docker version used to build this image

Id

string

The image ID

ManifestType

string

Media type of the manifest for the image

Os

string

The operating system family used to build this image, and required to run it

OsVersion

string

The version of the operating system used to build this image

Parent

string

The ID of the base image for this image

RootFS

RootFS contains information about the root filesystem of a container image

Size

integer

The size of the image in bytes

VirtualSize

integer

The sum of the size of each layer in the image in bytes

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have authorization to access the specified namespace.

code

string

message

string

rc

integer

request-id

string

404 - The specified image was not found. Check the spelling of the specified image.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get image manifest

GET /api/v1/images/{image}/manifest

Get the manifest for a container image in the private registry.

Request

Path Parameters

image

Required *

string

The full IBM Cloud registry path to the image that you want to inspect. Run `ibmcloud cr images` or call the `GET /images/json` endpoint to review images that are in the registry.

Query Parameters

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have authorization to access the specified namespace.

code

string

message

string

rc

integer

request-id

string

404 - The specified image was not found. Check the spelling of the specified image.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get messages

GET /api/v1/messages

Return any published system messages.

Request

Response

200 - Success.

204 - There are no messages to display.

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

List namespaces

GET /api/v1/namespaces

List authorized namespaces in the targeted IBM Cloud account.

Request

Path Parameters

Query Parameters

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Detailed namespace list

GET /api/v1/namespaces/details

Retrieves details, such as resource group, for all your namespaces in the targeted registry.

Request

Path Parameters

Query Parameters

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Create namespace

PUT /api/v1/namespaces/{name}

Add a namespace to the targeted IBM Cloud account.

Request

Path Parameters

name

Required *

string

The name of the namespace that you want to create.

Query Parameters

Response

200 - The namespace is already assigned to your IBM Cloud account.

namespace

string

201 - The namespace was successfully added to your IBM Cloud account.

namespace

string

400 - A required header is missing or invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - The requested namespace is blocklisted. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

409 - The requested namespace is already in use. Request a different namespace.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Assign namespace

PATCH /api/v1/namespaces/{name}

Assign a namespace to the specified resource group in the targeted IBM Cloud account.

Request

Path Parameters

name

Required *

string

The name of the namespace that you want to udpate.

Query Parameters

Response

200 - The namespace was successfully assigned to the resource group.

namespace

string

400 - A required header is missing or invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

404 - The requested account does not own a namespace with the requested name. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

409 - The requested namespace is already assigned to a resource group. Namespaces cannot be reassigned.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Delete namespace

DELETE /api/v1/namespaces/{name}

Delete the IBM Cloud Container Registry namespace from the targeted IBM Cloud account, and removes all images that were in that namespace.

Request

Path Parameters

name

Required *

string

The name of the namespace that you want to delete.

Query Parameters

Response

204 - Success.

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - Your IBM Cloud bearer token is not valid for the targeted account. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - The specified namespace is not owned by the targeted account.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get plans

GET /api/v1/plans

Get plans for the targeted account.

Request

Path Parameters

Query Parameters

Response

200 - Success.

plan

string

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Update plans

PATCH /api/v1/plans

Update plans for the targeted account.

Request

Request Body

Plan

A JSON document containing the requested updates.

plan

string

Path Parameters

Query Parameters

Response

200 - Success.

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to perform the requested operation. You must have either Manager or Billing Manager roles on the targeted account to perform this action.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get quotas

GET /api/v1/quotas

Get quotas for the targeted account.

Request

Path Parameters

Query Parameters

Response

200 - Success.

limit

QuotaDetails

usage

QuotaDetails

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Update quotas

PATCH /api/v1/quotas

Update quotas for the targeted account.

Request

Request Body

QuotaUpdate

A JSON document containing the requested updates.

storage_megabytes

integer

Storage quota in megabytes. The value -1 denotes "Unlimited".

traffic_megabytes

integer

Traffic quota in megabytes. The value -1 denotes "Unlimited".

store

integer

Requested storage quota in megabytes. The value of Max Uint64 (18446744073709551615) denotes "Unlimited". This value is ignored if storage_megabytes is set to a non-zero value.

traffic

integer

Requested traffic quota in megabytes. The value of Max Uint64 (18446744073709551615) denotes "Unlimited". This value is ignored if traffic_megabytes is set to a non-zero value.

Path Parameters

Query Parameters

Response

200 - Success.

400 - A required header is missing or invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to perform the requested operation. You must have either Manager or Billing Manager roles on the targeted account to perform this action.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

List retention policies

GET /api/v1/retentions

List retention policies for all namespaces in the targeted IBM Cloud account.

Request

Path Parameters

Query Parameters

Response

200 - Success.

500 -

503 -

Set retention policy

POST /api/v1/retentions

Set the retention policy for the specified namespace.

Request

Request Body

RetentionPolicy

The retention policy parameters to be applied to the namespace, as JSON.

account

string

Account associated with the policy.

images_per_repo

integer

Determines how many images are retained in each repository when the retention policy is processed. The default value -1 denotes 'Unlimited' (all images are retained). Additional images might be retained in each repository if the retention setting 'deletion_threshold_days' is used.

deletion_threshold_days

integer

Sets an age threshold after which images can be deleted by the retention policy. Images under this age are always retained, regardless of the 'images_per_repo' value. The default value 0 denotes no threshold.

namespace

Required *

string

The namespace to which the retention policy is attached.

retain_untagged

boolean

Determines whether untagged images are retained when the retention policy is processed. The value is false by default, which means that untagged images can be deleted when the policy runs.

Path Parameters

Query Parameters

Response

200 - Success.

400 - Supplied input was not valid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to the specified namespace. Choose another namespace.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Analyze retention policy

POST /api/v1/retentions/analyze

Analyze a retention policy, and get a list of what would be deleted by it.

Request

Request Body

RetentionPolicy

The retention policy parameters to be analyzed, as JSON.

account

string

Account associated with the policy.

images_per_repo

integer

deletion_threshold_days

integer

namespace

Required *

string

The namespace to which the retention policy is attached.

retain_untagged

boolean

Determines whether untagged images are retained when the retention policy is processed. The value is false by default, which means that untagged images can be deleted when the policy runs.

Path Parameters

Query Parameters

Response

200 - Success.

400 - Supplied input was not valid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Get retention policy

GET /api/v1/retentions/{namespace}

Get the retention policy for the specified namespace.

Request

Path Parameters

namespace

Required *

string

Gets the retention policy for the specified namespace.

Query Parameters

Response

200 - Success.

account

string

Account associated with the policy.

images_per_repo

integer

deletion_threshold_days

integer

namespace

string

The namespace to which the retention policy is attached.

retain_untagged

boolean

Determines whether untagged images are retained when the retention policy is processed. The value is false by default, which means that untagged images can be deleted when the policy runs.

400 - Supplied input was not valid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have access to the specified namespace. Choose another namespace.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Delete tag

DELETE /api/v1/tags/{image}

Untag a container image in the registry.

Request

Path Parameters

image

Required *

string

The name of the image that you want to delete, in the format <REPOSITORY>:<TAG>

Query Parameters

Response

200 - Success

Untagged

string

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have authorization to access the specified namespace.

code

string

message

string

rc

integer

request-id

string

404 - The specified image was not found. Check the spelling of the specified image.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

List deleted images

GET /api/v1/trash

List all images that are in the trash can.

Request

Path Parameters

Query Parameters

namespace

string

Limit results to trash can images in the given namespace only.

Response

200 - Success

400 - A required header is missing. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

401 - You are not authorized to view the requested resource, or your IBM Cloud bearer token is invalid. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - No namespaces exist for this account, or you are not authorized to view any namespaces for this account in this region. Create a namespace, or ensure that the IAM access policy for this account grants you Reader access to at least one namespace. You must have access to at least one namespace so that you can list the contents of the trash can

code

string

message

string

rc

integer

request-id

string

404 - No namespaces were found for the targeted account. Add a namespace or target a different account

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Restore a digest and all associated tags

POST /api/v1/trash/{digest}/restoretags

In the targeted region, restore a digest, and all of its tags in the same repository, from the trash.

Request

Path Parameters

digest

Required *

string

The full IBM Cloud registry digest reference for the digest that you want to restore such as `icr.io/namespace/repo@sha256:a9be...`. Call the `GET /trash/json` endpoint to review digests that are in the trash and their tags in the same repository.

Query Parameters

Response

200 - Success

successful

array

Successful is a list of tags that were restored

unsuccessful

array

Unsuccessful is a list of tags that were not restored because of a conflict

400 - There was a problem with the input. Correct the request and try again.

code

string

message

string

rc

integer

request-id

string

403 - You do not have push authorization to the specified namespace.

code

string

message

string

rc

integer

request-id

string

404 - Digest not found.

code

string

message

string

rc

integer

request-id

string

500 -

503 -

Restore deleted image

POST /api/v1/trash/{image}/restore

Restore an image from the trash can.

Request

Path Parameters

image

Required *

string

The name of the image that you want to restore, in the format <REPOSITORY>:<TAG>. Run `ibmcloud cr trash-list` or call the `GET /trash/json` endpoint to review images that are in the trash.