Registry APIv1

Download OpenAPI

Introduction

Container Registry API completes the docker command line to allow you to fully manage your namespaces, images and tags.

Registries

A Registry is a service which stores docker images. Container Registry proposes one registry per region (currently nl-ams and fr-par)

Getting Started

Please note that examples below are using ams1 region (nl-ams), but you may also use par1 (fr-par) if you want by replacing { "region": "ams1" } to { "region": "par1" } in namespace POST request. Then, change registry host from rg.nl-ams.scw.cloud to rg.fr-par.scw.cloud.

Create a namespace:

curl -X POST --header "x-auth-token: ${SCALEWAY_TOKEN}" https://api.scaleway.com/registry/v1/namespaces -d '{"name": "myfirstnamespace", "organization_id": "${SCALEWAY_ORG}", "description": "mydevnamespace", "region": "ams1"}'

Push an image:

docker login rg.nl-ams.scw.cloud -u anyuser -p ${SCALEWAY_TOKEN}`
docker tag nginx:latest rg.nl-ams.scw.cloud/myfirstnamespace/nginx:latest
docker push rg.nl-ams.scw.cloud/myfirstnamespace/nginx:latest

Namespaces

To use our services, the first step is to create a namespace.

A namespace is for images what a folder is for files. Every push or pull must mention the namespace : docker pull rg.nl-ams.scw.cloud/<namespace_name>/<image_name>:<tag_name>

Note that a namespace name is unique on a region. Thus, if another client already has created "test", you can't have it as a namespace

A namespace can be either public or private (default), which determines who can pull images.

List all your namespaces

GET
/registry/v1/regions/{region}/namespaces
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
Query Parameters
page
number
A positive integer to choose the page to display. The default value is 1.
page_size
number
A positive integer lower or equal to 100 to select the number of items to display. The default value is 20.
order_by
string
Field by which to order the display of Images. Possible values are created_at_asc, created_at_desc, description_asc, description_desc, name_asc and name_desc. The default value is created_at_asc.
organization_id
nullable string
Filter by the namespace owner.
name
nullable string
Filter by the namespace name (exact match).
200 Response
namespaces
array
Paginated list of namespaces matching filters.
id
string
The unique ID of the namespace.
name
string
The name of the namespace, unique in a region accross all organizations.
description
string
Description of the namespace.
organization_id
string
Owner of the namespace.
status
string
Namespace status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
string
Namespace status details.
endpoint
string
Endpoint reachable by docker.
is_public
boolean
Namespace visibility policy.
size
number
Total size of the namespace, calculated as the sum of the size of all images in the namespace.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
image_count
number
Number of images in the namespace.
region
string
Region the namespace belongs to.
total_count
number
Total number of namespaces matching filters.
Response Example
{
  "namespaces": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "organization_id": "string",
      "status": "unknown",
      "status_message": "string",
      "endpoint": "string",
      "is_public": "boolean",
      "size": 42,
      "created_at": "string",
      "updated_at": "string",
      "image_count": 42,
      "region": "string"
    }
  ],
  "total_count": 42
}

Create a new namespace

POST
/registry/v1/regions/{region}/namespaces
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
Body
name
string
Define a namespace name.
description
string
Define a description.
organization_id
string
Define the namespace owner.
is_public
boolean
Define the default visibility policy.
Request Example
{
  "name": "string",
  "description": "string",
  "organization_id": "string",
  "is_public": "boolean"
}
200 Response
id
string
The unique ID of the namespace.
name
string
The name of the namespace, unique in a region accross all organizations.
description
string
Description of the namespace.
organization_id
string
Owner of the namespace.
status
string
Namespace status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
string
Namespace status details.
endpoint
string
Endpoint reachable by docker.
is_public
boolean
Namespace visibility policy.
size
number
Total size of the namespace, calculated as the sum of the size of all images in the namespace.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
image_count
number
Number of images in the namespace.
region
string
Region the namespace belongs to.
Response Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "organization_id": "string",
  "status": "unknown",
  "status_message": "string",
  "endpoint": "string",
  "is_public": "boolean",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "image_count": 42,
  "region": "string"
}

Get a namespace

Get the namespace associated with the given id.

GET
/registry/v1/regions/{region}/namespaces/{namespace_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
namespace_id
required string
The unique ID of the Namespace.
200 Response
id
string
The unique ID of the namespace.
name
string
The name of the namespace, unique in a region accross all organizations.
description
string
Description of the namespace.
organization_id
string
Owner of the namespace.
status
string
Namespace status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
string
Namespace status details.
endpoint
string
Endpoint reachable by docker.
is_public
boolean
Namespace visibility policy.
size
number
Total size of the namespace, calculated as the sum of the size of all images in the namespace.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
image_count
number
Number of images in the namespace.
region
string
Region the namespace belongs to.
Response Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "organization_id": "string",
  "status": "unknown",
  "status_message": "string",
  "endpoint": "string",
  "is_public": "boolean",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "image_count": 42,
  "region": "string"
}

Update an existing namespace

Update the namespace associated with the given id.

PATCH
/registry/v1/regions/{region}/namespaces/{namespace_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
namespace_id
required string
Namespace ID to update.
Body
description
nullable string
Define a description.
is_public
nullable boolean
Define the default visibility policy.
Request Example
{
  "description": "string",
  "is_public": "boolean"
}
200 Response
id
string
The unique ID of the namespace.
name
string
The name of the namespace, unique in a region accross all organizations.
description
string
Description of the namespace.
organization_id
string
Owner of the namespace.
status
string
Namespace status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
string
Namespace status details.
endpoint
string
Endpoint reachable by docker.
is_public
boolean
Namespace visibility policy.
size
number
Total size of the namespace, calculated as the sum of the size of all images in the namespace.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
image_count
number
Number of images in the namespace.
region
string
Region the namespace belongs to.
Response Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "organization_id": "string",
  "status": "unknown",
  "status_message": "string",
  "endpoint": "string",
  "is_public": "boolean",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "image_count": 42,
  "region": "string"
}

Delete an existing namespace

Delete the namespace associated with the given id.

DELETE
/registry/v1/regions/{region}/namespaces/{namespace_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
namespace_id
required string
The unique ID of the Namespace.
200 Response
id
string
The unique ID of the namespace.
name
string
The name of the namespace, unique in a region accross all organizations.
description
string
Description of the namespace.
organization_id
string
Owner of the namespace.
status
string
Namespace status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
string
Namespace status details.
endpoint
string
Endpoint reachable by docker.
is_public
boolean
Namespace visibility policy.
size
number
Total size of the namespace, calculated as the sum of the size of all images in the namespace.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
image_count
number
Number of images in the namespace.
region
string
Region the namespace belongs to.
Response Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "organization_id": "string",
  "status": "unknown",
  "status_message": "string",
  "endpoint": "string",
  "is_public": "boolean",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "image_count": 42,
  "region": "string"
}

Images

An image represents a docker image.

The visibility of an image can be public (everyone can pull it), private (only your organization can pull it) or inherit from the namespace visibility (default) It can be changed with an update on the image via the registry API.

List all your images

GET
/registry/v1/regions/{region}/images
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
Query Parameters
page
number
A positive integer to choose the page to display. The default value is 1.
page_size
number
A positive integer lower or equal to 100 to select the number of items to display. The default value is 20.
order_by
string
Field by which to order the display of Images. Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.
namespace_id
nullable string
Filter by the Namespace ID.
name
nullable string
Filter by the Image name (exact match).
organization_id
nullable string
Filter by Organization ID.
200 Response
images
array
Paginated list of images matching filters.
id
string
The unique ID of the Image.
name
string
The Image name, unique in a namespace.
namespace_id
string
The unique ID of the Namespace the image belongs to.
status
string
The status of the image. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
nullable string
Details of the image status.
visibility
string
A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter. Possible values are visibility_unknown, inherit, public and private. The default value is visibility_unknown.
size
number
Image size in bytes, calculated from the size of image layers. One layer used in two tags of the same image is counted once but one layer used in two images is counted twice.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
tags
array
List of docker tags of the image.
total_count
number
Total number of images matching filters.
Response Example
{
  "images": [
    {
      "id": "string",
      "name": "string",
      "namespace_id": "string",
      "status": "unknown",
      "status_message": "string",
      "visibility": "visibility_unknown",
      "size": 42,
      "created_at": "string",
      "updated_at": "string",
      "tags": [
        "string"
      ]
    }
  ],
  "total_count": 42
}

Get a image

Get the image associated with the given id.

GET
/registry/v1/regions/{region}/images/{image_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
image_id
required string
The unique ID of the Image.
200 Response
id
string
The unique ID of the Image.
name
string
The Image name, unique in a namespace.
namespace_id
string
The unique ID of the Namespace the image belongs to.
status
string
The status of the image. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
nullable string
Details of the image status.
visibility
string
A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter. Possible values are visibility_unknown, inherit, public and private. The default value is visibility_unknown.
size
number
Image size in bytes, calculated from the size of image layers. One layer used in two tags of the same image is counted once but one layer used in two images is counted twice.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
tags
array
List of docker tags of the image.
Response Example
{
  "id": "string",
  "name": "string",
  "namespace_id": "string",
  "status": "unknown",
  "status_message": "string",
  "visibility": "visibility_unknown",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "tags": [
    "string"
  ]
}

Update an existing image

Update the image associated with the given id.

PATCH
/registry/v1/regions/{region}/images/{image_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
image_id
required string
Image ID to update.
Body
visibility
string
A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter. Possible values are visibility_unknown, inherit, public and private. The default value is visibility_unknown.
Request Example
{
  "visibility": "visibility_unknown"
}
200 Response
id
string
The unique ID of the Image.
name
string
The Image name, unique in a namespace.
namespace_id
string
The unique ID of the Namespace the image belongs to.
status
string
The status of the image. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
nullable string
Details of the image status.
visibility
string
A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter. Possible values are visibility_unknown, inherit, public and private. The default value is visibility_unknown.
size
number
Image size in bytes, calculated from the size of image layers. One layer used in two tags of the same image is counted once but one layer used in two images is counted twice.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
tags
array
List of docker tags of the image.
Response Example
{
  "id": "string",
  "name": "string",
  "namespace_id": "string",
  "status": "unknown",
  "status_message": "string",
  "visibility": "visibility_unknown",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "tags": [
    "string"
  ]
}

Delete an image

Delete the image associated with the given id.

DELETE
/registry/v1/regions/{region}/images/{image_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
image_id
required string
The unique ID of the Image.
200 Response
id
string
The unique ID of the Image.
name
string
The Image name, unique in a namespace.
namespace_id
string
The unique ID of the Namespace the image belongs to.
status
string
The status of the image. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
status_message
nullable string
Details of the image status.
visibility
string
A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter. Possible values are visibility_unknown, inherit, public and private. The default value is visibility_unknown.
size
number
Image size in bytes, calculated from the size of image layers. One layer used in two tags of the same image is counted once but one layer used in two images is counted twice.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
tags
array
List of docker tags of the image.
Response Example
{
  "id": "string",
  "name": "string",
  "namespace_id": "string",
  "status": "unknown",
  "status_message": "string",
  "visibility": "visibility_unknown",
  "size": 42,
  "created_at": "string",
  "updated_at": "string",
  "tags": [
    "string"
  ]
}

Tags

A tag represents a docker tag of an image.

List all your tags

GET
/registry/v1/regions/{region}/images/{image_id}/tags
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
image_id
required string
The unique ID of the image.
Query Parameters
page
number
A positive integer to choose the page to display. The default value is 1.
page_size
number
A positive integer lower or equal to 100 to select the number of items to display. The default value is 20.
order_by
string
Field by which to order the display of Images. Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.
name
nullable string
Filter by the tag name (exact match).
200 Response
tags
array
Paginated list of tags matching filters.
id
string
The unique ID of the tag.
name
string
Tag name, unique for an image.
image_id
string
Image ID this tag belongs to.
status
string
Tag status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
digest
string
Hash of the tag actual content. Several tags of a same image may have the same digest.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
total_count
number
Total number of tags matching filters.
Response Example
{
  "tags": [
    {
      "id": "string",
      "name": "string",
      "image_id": "string",
      "status": "unknown",
      "digest": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "total_count": 42
}

Get a tag

Get the tag associated with the given id.

GET
/registry/v1/regions/{region}/tags/{tag_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
tag_id
required string
The unique ID of the Tag.
200 Response
id
string
The unique ID of the tag.
name
string
Tag name, unique for an image.
image_id
string
Image ID this tag belongs to.
status
string
Tag status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
digest
string
Hash of the tag actual content. Several tags of a same image may have the same digest.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
Response Example
{
  "id": "string",
  "name": "string",
  "image_id": "string",
  "status": "unknown",
  "digest": "string",
  "created_at": "string",
  "updated_at": "string"
}

Delete a tag

Delete the tag associated with the given id.

DELETE
/registry/v1/regions/{region}/tags/{tag_id}
Path Parameters
region
required string
The region you want to target. Possible values are fr-par and nl-ams.
tag_id
required string
The unique ID of the tag.
Query Parameters
force
boolean
If two tags share the same digest the deletion will fail unless this parameter is set to true.
200 Response
id
string
The unique ID of the tag.
name
string
Tag name, unique for an image.
image_id
string
Image ID this tag belongs to.
status
string
Tag status. Possible values are unknown, ready, deleting, error and locked. The default value is unknown.
digest
string
Hash of the tag actual content. Several tags of a same image may have the same digest.
created_at
string
Creation date.
updated_at
string
Last modification date, from the user or the service.
Response Example
{
  "id": "string",
  "name": "string",
  "image_id": "string",
  "status": "unknown",
  "digest": "string",
  "created_at": "string",
  "updated_at": "string"
}