---
updatedAt: 2026-09-08T09:40:39.000Z
agentTools:
  projectIndex: https://docs.scalr.io/llms.txt
---

# Create a container image

Register an account-scoped custom container image repository.
The repository's semantic version tags are synchronized automatically.

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "ContainerImage": {
        "properties": {
          "attributes": {
            "properties": {
              "created-at": {
                "description": "The resource creation timestamp.",
                "format": "date-time",
                "readOnly": true,
                "type": "string"
              },
              "description": {
                "description": "Optional image description.",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              },
              "last-synced-at": {
                "description": "The timestamp of the last successful synchronization.",
                "format": "date-time",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              },
              "name": {
                "description": "The container image repository name without a tag, for example scalr/runner.",
                "readOnly": true,
                "type": "string"
              },
              "registry-url": {
                "default": "https://registry-1.docker.io",
                "description": "Public OCI registry URL. Defaults to Docker Hub when omitted and cannot be changed after registration.",
                "type": "string"
              },
              "repository": {
                "description": "Repository path within the registry, without a host, tag, or digest, for example `myorg/runner`. It cannot be changed after registration.",
                "type": "string"
              },
              "sync-error": {
                "description": "The last synchronization error, if any.",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              },
              "sync-status": {
                "description": "Tag synchronization state of the image.",
                "enum": [
                  "pending",
                  "synced",
                  "failed",
                  "no_versions"
                ],
                "readOnly": true,
                "type": "string"
              },
              "visibility": {
                "description": "Image visibility: a Scalr-managed system image or an account-scoped public custom image.",
                "enum": [
                  "system",
                  "public"
                ],
                "readOnly": true,
                "type": "string"
              }
            },
            "required": [
              "repository"
            ],
            "type": "object"
          },
          "id": {
            "readOnly": true,
            "type": "string"
          },
          "links": {
            "properties": {
              "self": {
                "readOnly": true,
                "type": "string"
              }
            },
            "readOnly": true,
            "type": "object"
          },
          "relationships": {
            "properties": {
              "latest-version": {
                "description": "The latest version registered for this container image.",
                "properties": {
                  "data": {
                    "nullable": true,
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "type": {
                        "enum": [
                          "container-image-versions",
                          ""
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ],
                    "type": "object"
                  }
                },
                "readOnly": true,
                "required": [
                  "data"
                ],
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": {
            "enum": [
              "container-images"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "attributes"
        ],
        "type": "object"
      },
      "ContainerImageDocument": {
        "description": "JSON:API Document.\n\nsee: https://jsonapi.org/format/#document-structure",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ContainerImage"
          },
          "included": {
            "items": {
              "type": "object"
            },
            "readOnly": true,
            "type": "array"
          },
          "meta": {
            "readOnly": true,
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "API-Key": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Scalr IACP API",
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "title": "Scalr IACP API",
    "version": "unversioned"
  },
  "openapi": "3.0.0",
  "paths": {
    "/container-images": {
      "post": {
        "description": "Register an account-scoped custom container image repository.\nThe repository's semantic version tags are synchronized automatically.",
        "operationId": "create_container_image",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "$ref": "#/components/schemas/ContainerImageDocument"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/vnd.api+json": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerImageDocument"
                }
              }
            },
            "description": ""
          },
          "403": {
            "description": "Custom runner images are not available for the account."
          },
          "409": {
            "description": "The repository is already registered in the account."
          },
          "4XX": {
            "description": "Client error."
          },
          "5XX": {
            "description": "Server error."
          }
        },
        "summary": "Create a container image",
        "tags": [
          "container-images"
        ],
        "x-resource": "ContainerImage",
        "x-service": "tf-api"
      }
    }
  },
  "security": [
    {
      "API-Key": []
    }
  ],
  "servers": [
    {
      "url": "https://{Domain}/api/iacp/v3",
      "variables": {
        "Domain": {
          "default": "example.scalr.io",
          "description": "Domain where Scalr is hosted"
        }
      }
    }
  ]
}
```

# Sibling pages

* [List container image versions](https://docs.scalr.io/scalr/reference/list_container_image_versions.md)
* [Get a container image version](https://docs.scalr.io/scalr/reference/get_container_image_version.md)
* [List container images](https://docs.scalr.io/scalr/reference/list_container_images.md)
* [Get a container image](https://docs.scalr.io/scalr/reference/get_container_image.md)
* [Delete a container image](https://docs.scalr.io/scalr/reference/delete_container_image.md)
* [Synchronize a container image](https://docs.scalr.io/scalr/reference/sync_container_image.md)