> ## 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 Application from Image

> Creates an application that runs from a custom Docker image.

The image must be ready (`status: "success"`). Several applications can share one image, each with its own variables. The language, version, main file, start and build commands do not apply: they come from the image. Needs the `apps:write` scope when called with an API key. See [Custom Docker images](https://docs.vertracloud.app/guides/custom-docker-images.md).

**image\_id** `string` *required*

The ID of the image the app runs from.

**name** `string` *required*

The application display name. Maximum 50 characters.

**memory** `integer` *required*

The amount of RAM to allocate, in MB.

**description** `string`

An application description.

**web** `boolean` *required*

`true` publishes the app on the web (`subdomain` and `port` apply). `false` creates an app without traffic, such as a bot or worker.

**subdomain** `string`

The subdomain for the app. Send `random` to let the platform pick one. Only with `web: true`.

**port** `integer`

The port the app listens on. Only with `web: true`. Default: the first `EXPOSE` of the image's `Dockerfile`, or `80`. The platform injects it as the `PORT` environment variable.

**envs** `object[]`

Environment variables, each with `key`, `value` and an optional `note`. Maximum key length 255, maximum value length 3072, maximum note length 50.

**workspace\_id** `string`

The workspace to associate with the application.

### Response

Creation is asynchronous: the response is `202 Accepted` with the application in `status: "building"` and `custom_image` filled in (`image_id`, `port`, `version_id`, `outdated`). The application has the same fields as in [Create Application](https://docs.vertracloud.app/api-reference/endpoint/apps/create.md). Follow it with [Application Details](https://docs.vertracloud.app/api-reference/endpoint/apps/get.md) until `status` is `up` or `down`.

```json Response theme={null}
{
  "response": {
    "id": "app-abc123def456",
    "name": "my-api-prod",
    "status": "building",
    "ram": 512,
    "subdomain": "myapp.vertraweb.app",
    "custom_image": {
      "id": "app-abc123def456",
      "name": "my-api-prod",
      "version_id": null,
      "outdated": false,
      "image_id": "img-abc123def456",
      "port": 3000
    }
  }
}
```

### 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 `apps:write` scope (`403`).
* `VALIDATION_ERROR`: The body failed validation (`400`).
* `IMAGE_NOT_FOUND`: The image does not exist or you cannot access it (`404`).
* `IMAGE_NOT_READY`: The image has no successful build yet (`409`).
* `MAX_APPS_REACHED`: The plan's application limit was reached (`403`).
* `MEMORY_BELOW_MINIMUM`, `MEMORY_LIMIT_EXCEEDED`: The memory is below the minimum or above what the plan still has (`400`).
* `SUBDOMAIN_TAKEN`, `SUBDOMAIN_FORBIDDEN`: The subdomain is in use or reserved (`409`, `400`).
* `PLAN_DOES_NOT_SUPPORT_WEB_PUBLISH`: `web: true` on a plan without web publishing (`403`).
* `DEPLOY_RATE_LIMITED`: The account's hourly deploy budget was reached (`429`).
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "IMAGE_NOT_READY"
}
```


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