---
title: "Create a container image"
method: POST
path: "/container-images"
tags: ["container-images"]
---

# Create a container image

`POST /container-images`

## Request

- Base URL: `https://example.scalr.io/api/iacp/v3`
- URL: `https://example.scalr.io/api/iacp/v3/container-images`
- Auth: HTTP bearer

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

## Request body

- ContainerImageDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure
  - `data` ContainerImage
    - `attributes` object, required
      - `created-at` string, date-time: The resource creation timestamp.
      - `description` string, nullable: Optional image description.
      - `last-synced-at` string, date-time, nullable: The timestamp of the last successful synchronization.
      - `name` string: The container image repository name without a tag, for example scalr/runner.
      - `registry-url` string: Public OCI registry URL. Defaults to Docker Hub when omitted and cannot be changed after registration.
      - `repository` string, required: Repository path within the registry, without a host, tag, or digest, for example `myorg/runner`. It cannot be changed after registration.
      - `sync-error` string, nullable: The last synchronization error, if any.
      - `sync-status` 'pending' | 'synced' | 'failed' | 'no_versions': Tag synchronization state of the image.
      - `visibility` 'system' | 'public': Image visibility: a Scalr-managed system image or an account-scoped public custom image.
    - `id` string
    - `links` object
      - `self` string
    - `relationships` object
      - `latest-version` object: The latest version registered for this container image.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'container-image-versions' | '', required
    - `type` 'container-images', required
  - `included` object[]
  - `meta` object

## Response `201`

- ContainerImageDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure
  - `data` ContainerImage
    - `attributes` object, required
      - `created-at` string, date-time: The resource creation timestamp.
      - `description` string, nullable: Optional image description.
      - `last-synced-at` string, date-time, nullable: The timestamp of the last successful synchronization.
      - `name` string: The container image repository name without a tag, for example scalr/runner.
      - `registry-url` string: Public OCI registry URL. Defaults to Docker Hub when omitted and cannot be changed after registration.
      - `repository` string, required: Repository path within the registry, without a host, tag, or digest, for example `myorg/runner`. It cannot be changed after registration.
      - `sync-error` string, nullable: The last synchronization error, if any.
      - `sync-status` 'pending' | 'synced' | 'failed' | 'no_versions': Tag synchronization state of the image.
      - `visibility` 'system' | 'public': Image visibility: a Scalr-managed system image or an account-scoped public custom image.
    - `id` string
    - `links` object
      - `self` string
    - `relationships` object
      - `latest-version` object: The latest version registered for this container image.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'container-image-versions' | '', required
    - `type` 'container-images', required
  - `included` object[]
  - `meta` object

## Other responses

- `403`: Custom runner images are not available for the account.
- `409`: The repository is already registered in the account.
- `4XX`: Client error.
- `5XX`: Server error.

## Changes

- **2026-11-03** `d3e1dc85657a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scalr/apis/scalr-iacp-api/changes/container-images/post.md)

---

[API](https://skmtc.dev/scalr/apis/scalr-iacp-api.md) - [All operations](https://skmtc.dev/scalr/apis/scalr-iacp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scalr/apis/scalr-iacp-api/revisions/d3e1dc85657a?raw)