IBM Cloud Container Registry

IBM® Cloud Container Registry provides a multi-tenant, highly available, and scalable private image registry that is hosted and managed by IBM. You can use the private registry by setting up your own image namespace and pushing Docker images to your namespace.

The endpoint for the IBM Cloud Container Registry API is in the format: https://<registry_dns_name> For example, the API endpoint for Dallas is: https://us.icr.io To find out about the available IBM Cloud Container Registry DNS names, see Regions.

If you want to find the endpoint for the registry that you are currently targeting, run the ibmcloud cr api command.

For more information about IBM Cloud Container Registry, see About IBM Cloud Container Registry.

For more information about IBM Cloud Kubernetes Service, see Getting started with IBM Cloud Kubernetes Service.

Related APIs:

Error handling

The IBM Cloud Container Registry service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates a failure, and a 500 type response usually indicates an internal system error.

Methods

Get authorization options for the targeted account.

GET /api/v1/auth
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Response

AuthResponse contains information about the requested authorization updates for the targeted IBM Cloud account

Status Code

  • Success

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

  • An internal server error occurred. Try again later.

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Update authorization options for the targeted account.

PATCH /api/v1/auth
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

A JSON document containing the requested updates.

Response

Status Code

  • Success

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

  • 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.

  • An internal server error occurred. Try again later.

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Build a Docker image.

POST /api/v1/builds
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The IBM Cloud IAM refresh token that you receive when you log in to IBM Cloud. Your refresh token is stored in your IBM Cloud config file: ~/.bluemix/config.json

  • The unique ID for your IBM Cloud account.

Query Parameters

  • The full name for the image that you want to build, including the registry URL and namespace.

  • Specify the location of the Dockerfile relative to the build context. If not specified, the default is 'PATH/Dockerfile', where PATH is the root of the build context.

  • If set to true, cached image layers from previous builds are not used in this build. Use this option if you expect the result of commands that run in the build to change.

  • If set to true, the base image is pulled even if an image with a matching tag already exists on the build host. The base image is specified by using the FROM keyword in your Dockerfile. Use this option to update the version of the base image on the build host.

  • If set to true, the filesystem of the built image is reduced to one layer before it is pushed to the registry. Use this option if the number of layers in your image is close to the maximum for your storage driver.

  • A JSON key-value structure that contains build arguments. The value of the build arguments are available as environment variables when you specify an ARG line which matches the key in your Dockerfile.

  • If set to true, build output is suppressed unless an error occurs.

Response

buildoutput is used in Swagger doc

Status Code

  • A stream of JSON objects that contain the output from the build host.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

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

GET /api/v1/images
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Query Parameters

  • 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.

  • 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.

  • 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.

  • 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.

  • 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

RemoteAPIImage contains information about an image. /api/v1/images returns a RemoteAPIImage for each image in the targeted IBM Cloud account

Status Code

  • Success

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

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

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

  • 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.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Remove multiple Docker images from the registry.

POST /api/v1/images/bulkdelete
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

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.

Response

Success is a list of digests which were deleted successfully. Error is a map of digests to the error object that explains the failure.

Status Code

  • Success

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

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

In the region that you're logged into, create a new tag in a private registry that refers to an existing image in the same region.

POST /api/v1/images/tags
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Query Parameters

  • The full IBM Cloud registry path to the image that you want to create a new tag for, in the format :. Run ibmcloud cr images or call the GET /images/json endpoint to review images that are in the registry.

  • The full IBM Cloud registry path where you want to put the new tag, in the format :.

Response

Status Code

  • Success

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

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

  • You do not have authorization to access the specified namespace.

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Remove a Docker image from the registry.

DELETE /api/v1/images/{image}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • 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.

Response

Status Code

  • Success

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

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

  • You do not have authorization to access the specified namespace.

  • The specified image was not found. Check the spelling of the specified image.

  • Inspecting a manifest-list is not supported

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Inspect a Docker image in the private registry.

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

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • 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.

Response

ImageInspection is an image JSON output consistent with the Docker Remote API

Status Code

  • Success

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

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

  • You do not have authorization to access the specified namespace.

  • The specified image was not found. Check the spelling of the specified image.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Return any published system messages.

GET /api/v1/messages
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Success.

  • There are no messages to display.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

List authorized namespaces in the targeted IBM Cloud account.

GET /api/v1/namespaces
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Response

namespaces is a list of authorized namespaces in the targeted IBM Cloud account

Status Code

  • Success

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

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Add a namespace to the targeted IBM Cloud account.

PUT /api/v1/namespaces/{namespace}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • Adds the specified namespace to your IBM Cloud account.

Response

Status Code

  • The namespace is already assigned to your IBM Cloud account.

  • The namespace was successfully added to your IBM Cloud account.

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

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

  • The requested namespace is blacklisted. Correct the request and try again.

  • The requested namespace is already in use. Request a different namespace.

  • An internal server error occurred. Try again later.

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

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

DELETE /api/v1/namespaces/{namespace}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • The namespace that you want to delete.

Response

Status Code

  • Success.

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

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

  • The specified namespace is not owned by the targeted account.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Get plans for the targeted account.

GET /api/v1/plans
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Response

PlanResponse contains information about the requested plan updates for the targeted IBM Cloud account

Status Code

  • Success.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Update plans for the targeted account.

PATCH /api/v1/plans
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

A JSON document containing the requested updates.

Response

Status Code

  • Success.

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

  • 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.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Get quotas for the targeted account.

GET /api/v1/quotas
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Response

QuotaAPIResponse contains current usage and limits, used as the response format for GetQuota

Status Code

  • Success.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Update quotas for the targeted account.

PATCH /api/v1/quotas
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

A JSON document containing the requested updates.

Response

Status Code

  • Success.

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

  • 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.

  • An internal server error occurred. Try again later.

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

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

POST /api/v1/retentions/analyze
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

The retention policy parameters to be analyzed, as JSON.

Response

AnalysisResponse is the type returned from a Retention Policy Analysis call

Status Code

  • Success.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Untags a Docker image in the registry.

DELETE /api/v1/tags/{image}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • The full IBM Cloud registry path to the image that you want to delete, including its tag.

Response

Status Code

  • Success

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

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

  • You do not have authorization to access the specified namespace.

  • The specified image was not found. Check the spelling of the specified image.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

List all valid registry access tokens for an owner.

GET /api/v1/tokens
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Response

ListTokensResp represents the server response to a successful token list request

Status Code

  • Success.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Issue a registry access token for the targeted IBM Cloud account.

POST /api/v1/tokens
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Query Parameters

  • Specifies a description for the token so it can be more easily identified. If this option is specified more than once, the last parsed setting is the setting that is used.

  • When specified, the access token does not expire. If this option is specified more than once, the last parsed setting is the setting that is used.

  • When specified, the token provides write access to registry namespaces in your IBM Cloud account. If this option is not specified, or is set to false, the token provides read-only access. If this option is specified more than once, the last parsed setting is the setting that is used.

Response

Token is a JSON struct for responses from Bouncer

Status Code

  • Success.

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

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Revoke all registry access tokens that match a query.

DELETE /api/v1/tokens
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Query Parameters

  • Specifies a second owner field for the token. If this option is specified more than once, the last parsed setting is the setting that is used.

Response

Status Code

  • Success.

  • A required parameter is missing. Correct the request and try again.

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

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Revoke the specified registry access token.

DELETE /api/v1/tokens/{token}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • The token that you want to delete.

Response

Status Code

  • Success.

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

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

  • The specific token was not found in your account. Correct the request and try again.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.

Retrieve the registry token with the given UUID.

GET /api/v1/tokens/{uuid}
Request

Custom Headers

  • The IBM Cloud IAM access token that you receive when you log in to IBM Cloud. Run ibmcloud iam oauth-tokens to retrieve your access token, which is prefixed with 'Bearer'.

  • The unique ID for your IBM Cloud account.

Path Parameters

  • The uuid of the token you wish to retrieve

Response

Token is a JSON struct for responses from Bouncer

Status Code

  • Success.

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

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

  • No token with the specific ID was found in your account. Correct the request and try again.

  • Internal server error

  • Unable to authenticate with IBM Cloud. Try again later.

No Sample Response

This method does not specify any sample responses.