> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Image

> Creates a custom Docker image from a build context (ZIP) or from a GitHub repository, and starts building it.

Available on **Enterprise 28, Enterprise 30 and Enterprise 32**. The request is `multipart/form-data`. The build context has **two mutually exclusive sources**: `file`, or `github_repository` (the branch is optional). It must have a file named exactly `Dockerfile` at its root; a single wrapping folder is accepted. `.env*` files are removed from the context and `.dockerignore` is respected. The `Dockerfile` is never rewritten. See [Custom Docker images](https://docs.vertracloud.app/guides/custom-docker-images.md) for the rules.

Needs the `images:write` scope when called with an API key. Check a `Dockerfile` first with [Check Dockerfile](https://docs.vertracloud.app/api-reference/endpoint/images/check.md).

**name** `string` *required*

The image name: 1 to 50 characters, unique among your images.

**description** `string`

Optional free-text description, up to 128 characters. An empty value means no description. You can change it later with [Update Image](https://docs.vertracloud.app/api-reference/endpoint/images/update.md).

**file** `file`

The build context: a ZIP file, up to 100 MB. Absent when the source is GitHub.

**github\_repository** `string`

Alternative to `file`: the GitHub repository to build from, as `owner/name`.

* A repository in one of your GitHub App installations is **linked** to the image: a push to the branch rebuilds it.
* A **public** repository outside your installations is built **once**, with no link (`github` is `null` in the response). To get automatic rebuilds, install the GitHub App on the repository and call [Link Image to GitHub](https://docs.vertracloud.app/api-reference/endpoint/images/github-link.md).
* A private or nonexistent repository outside your installations fails with `INSTALLATION_NOT_FOUND`.

**github\_branch** `string`

The branch of `github_repository` to build from. Optional: without it, the repository's default branch is used (`main`, `master` or whatever the repository sets). When the repository is linked, this is also the branch whose pushes rebuild the image. A branch that does not exist fails with `INSTALLATION_NOT_FOUND`.

**workspace\_id** `string`

The workspace that will own the image.

### Response

**response** `object`

The image. Creation is asynchronous: the response is `202 Accepted` with `status: "building"`. Follow it with [Get Image](https://docs.vertracloud.app/api-reference/endpoint/images/get.md) or the [build logs](https://docs.vertracloud.app/api-reference/endpoint/images/logs.md) until `status` is `success` or `failed`.

**Toggle object**

**id** `string`

The image ID.

**name** `string`

The image name.

**description** `string | null`

The image description (free text, up to 128 characters), or `null` when it has none.

**owner** `string`

`account` for your own images, `system` for images provided by the platform (these cannot be changed or deleted).

**status** `string`

State of the latest build: `building`, `success` or `failed`. A failed rebuild does not change the current version: apps keep running the last good one.

**error** `string | null`

Readable reason of the latest failed build, or `null`.

**digest** `string | null`

Digest (`sha256:...`) of the current version, or `null` while no build has succeeded.

**uncompressed\_bytes** `integer | null`

Size of the current version, uncompressed, in bytes.

**layer\_count** `integer | null`

Number of layers of the current version.

**apps** `object[]`

The applications created from this image. Each has `id`, `name`, `version_id` (the image version it runs, or `null`) and `outdated` (`true` when the image has a newer version; the app moves to it on the next restart or deploy you ask for).

**github** `object | null`

The linked GitHub repository and branch (`repository` as `owner/name`, `branch`), or `null` when the image is not linked, as when it was built once from a public repository.

**current\_version\_id** `string | null`

The current version of the image, or `null` while no build has succeeded.

**created\_at** `string`

When the image was created.

**updated\_at** `string`

When the image was last updated.

```json Response theme={null}
{
  "response": {
    "id": "img-abc123def456",
    "name": "my-api",
    "description": null,
    "owner": "account",
    "status": "building",
    "error": null,
    "digest": null,
    "uncompressed_bytes": null,
    "layer_count": null,
    "apps": [],
    "github": null,
    "current_version_id": null,
    "created_at": "2026-10-23T14:02:00Z",
    "updated_at": "2026-10-23T14:02:00Z"
  }
}
```

### Error Responses

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `API_KEY_SCOPE_DENIED`: The API key does not have the required scope (`403`).
* `VALIDATION_ERROR`: The multipart body failed validation, for example a `github_repository` that is not `owner/name` (`400`).
* `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`: The plan does not include custom Docker images (`403`).
* `MAX_IMAGES_REACHED`: The plan's limit of 20 images was reached; images in any state count (`403`).
* `DOCKERFILE_NOT_FOUND`: There is no file named exactly `Dockerfile` at the root of the context (`400`).
* `DOCKERFILE_REFUSED`: The `Dockerfile` has a refused instruction; `details` lists the findings (`400`). See [Check Dockerfile](https://docs.vertracloud.app/api-reference/endpoint/images/check.md).
* `IMAGE_CONTEXT_TOO_LARGE`: The build context is over a limit: more than 100 MB compressed, more than 512 MB uncompressed, more than 50,000 entries, or a `Dockerfile` larger than 1 MB (`413`).
* `IMAGE_BUILDER_UNAVAILABLE`: No host can build images right now; try again later (`503`).
* `INSTALLATION_NOT_FOUND`: The repository is private or does not exist, and it is not in your GitHub App installations; or the branch does not exist (`404`).
* `REPO_ALREADY_LINKED`: The repository is already linked to another image or application (`409`).
* `FETCH_ZIP_ERROR`: GitHub could not be reached or was limiting requests while the repository was fetched (`502`). Try again in a few minutes.
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "DOCKERFILE_REFUSED",
  "details": [{ "code": "run_network_host", "line": 7 }]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.