Container Registries API Endpoints

Manage container registries for deploying pre-built images with our API

Container registries allow you to connect external registries (Docker Hub, GHCR, custom) or use Nodion's built-in registries to deploy pre-built Docker images without a build step.

Nodion registries are created automatically for each region in your project. You can generate credentials for them to push your own images. External registries can be added with your own credentials.

Get Container Registries

To list all container registries of your project you can simply send a GET request to the following endpoint. This includes both Nodion-managed registries and your own external registries.

https://api.nodion.com/v1/container_registries

Required Headers: Authorization

Example Response:

{
  "container_registries": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "available",
      "registry_type": "nodion",
      "name": "Nodion Registry (Frankfurt, DE)",
      "hostname": "registry.fra.nodion.net",
      "has_credentials": false,
      "region_id": "428d037e-9ba6-4dab-92bd-8d816c523126",
      "created_at": "2025-01-15T10:00:00.000+01:00",
      "updated_at": "2025-01-15T10:00:00.000+01:00"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "status": "available",
      "registry_type": "docker_hub",
      "name": "My Docker Hub",
      "hostname": "docker.io",
      "has_credentials": true,
      "region_id": null,
      "created_at": "2025-02-01T14:30:00.000+01:00",
      "updated_at": "2025-02-01T14:30:00.000+01:00"
    }
  ]
}

Get Container Registry

To fetch a single container registry you can simply send a GET request to the following endpoint.

https://api.nodion.com/v1/container_registries/:id

Required Headers: Authorization

Example Response:

{
  "container_registry": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "available",
    "registry_type": "docker_hub",
    "name": "My Docker Hub",
    "hostname": "docker.io",
    "has_credentials": true,
    "region_id": null,
    "created_at": "2025-02-01T14:30:00.000+01:00",
    "updated_at": "2025-02-01T14:30:00.000+01:00"
  }
}

Create a Container Registry

To add an external container registry you can simply send a POST request to the following endpoint. Nodion registries are created automatically and cannot be created manually.

https://api.nodion.com/v1/container_registries

Required Headers: Authorization

Required Body Parameters:

name – A name for this registry.

registry_type – The type of registry. One of: docker_hub, ghcr, custom.

Optional Body Parameters:

hostname – The hostname of the registry (e.g. ghcr.io, registry.example.com). Defaults to docker.io for Docker Hub registries.

username – The username or access token for authentication.

password – The password or access token secret for authentication.

Possible Response Codes:

200 – The container registry was created successfully.
400 – There was something wrong. Please check the response.

Update a Container Registry

To update an external container registry you can simply send a PATCH request to the following endpoint. Nodion registries cannot be updated.

https://api.nodion.com/v1/container_registries/:id

Required Headers: Authorization

Optional Body Parameters:

name – A new name for the registry.

hostname – A new hostname for the registry.

username – Updated username or access token.

password – Updated password or access token secret.

Possible Response Codes:

200 – The container registry was updated successfully.
400 – There was something wrong. Please check the response.

Delete a Container Registry

To delete an external container registry you can simply send a DELETE request to the following endpoint. Nodion registries cannot be deleted.

https://api.nodion.com/v1/container_registries/:id

Required Headers: Authorization

Possible Response Codes:

200 – The container registry was deleted successfully.
400 – There was something wrong. Please check the response.

Generate Credentials for Nodion Registry

To generate push/pull credentials for a Nodion registry you can send a POST request to the following endpoint. This creates a robot account with minimal permissions (push and pull only) scoped to your project. Credentials can only be generated once – delete and recreate to rotate.

https://api.nodion.com/v1/container_registries/:id/credentials

Required Headers: Authorization

Possible Response Codes:

201 – Credentials were generated successfully.
400 – There was something wrong (e.g. credentials already exist or registry is not a Nodion registry).

Example Response:

{
  "container_registry": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hostname": "registry.fra.nodion.net",
    "username": "robot$project-a1b2c3d4",
    "password": "secret-token-value"
  }
}

Note: The username and password are only returned in this response. After this, only has_credentials: true will be shown. Use these credentials to push images to your Nodion registry:

docker login registry.fra.nodion.net -u "robot$project-a1b2c3d4" -p "secret-token-value"
docker push registry.fra.nodion.net/your-project-id/my-image:latest