> ## 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.

# Reconstruir imagem da fonte atual

> Constrói a imagem de novo sem enviar nada, a partir do contexto de build guardado ou da branch do GitHub vinculada.

A requisição não tem corpo. A fonte depende da imagem: uma imagem vinculada ao GitHub é construída a partir da ponta atual da branch vinculada; qualquer outra imagem é construída a partir do contexto do último build, **inclusive de um build que falhou**. Use para repetir um build que falhou sem enviar os arquivos de novo.

A reconstrução mantém o mesmo ID da imagem e, quando dá certo, adiciona uma nova [versão](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/versions.md). Ela conta no limite de deploys por hora como qualquer outro build, e uma reconstrução que falha mantém a versão atual. **As aplicações só são reiniciadas se a imagem estiver com `auto_update_apps` ligado**; caso contrário, cada app passa para a nova versão no próximo restart ou deploy que você pedir. Para construir com outros arquivos, use [Reconstruir imagem](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/rebuild.md).

Precisa do escopo `images:write` quando chamada com uma chave de API.

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

O ID da imagem.

**workspace\_id** `string`

Se a imagem pertencer a um workspace, o ID do workspace. Obrigatório para membros do workspace que agem sobre uma imagem que não é deles.

### Resposta

**response** `object`

A imagem. A resposta é `202 Accepted` com `status: "building"`.

**Mostrar objeto**

**id** `string`

O ID da imagem.

**name** `string`

O nome da imagem.

**description** `string | null`

A descrição da imagem (texto livre, até 128 caracteres), ou `null` quando ela não tem uma.

**owner** `string`

`account` para as suas imagens, `system` para imagens fornecidas pela plataforma (estas não podem ser alteradas nem apagadas).

**status** `string`

Estado do build mais recente: `building`, `success` ou `failed`. Uma reconstrução que falha não muda a versão atual: os apps continuam rodando a última versão que deu certo.

**error** `string | null`

Motivo legível do último build que falhou, ou `null`.

**digest** `string | null`

Digest (`sha256:...`) da versão atual, ou `null` enquanto nenhum build tiver dado certo.

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

Tamanho da versão atual, descompactada, em bytes.

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

Número de camadas da versão atual.

**apps** `object[]`

Os apps criados a partir desta imagem. Cada um tem `id`, `name`, `version_id` (a versão da imagem que ele executa, ou `null`) e `outdated` (`true` quando a imagem tem uma versão mais nova; o app passa para ela no próximo restart ou deploy que você pedir).

**github** `object | null`

O repositório e a branch do GitHub vinculados (`repository` no formato `owner/name`, `branch`), ou `null` quando a imagem não está vinculada.

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

A versão atual da imagem, ou `null` enquanto nenhum build tiver dado certo.

**created\_at** `string`

Quando a imagem foi criada.

**updated\_at** `string`

Quando a imagem foi atualizada pela última vez.

```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"
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `API_KEY_SCOPE_DENIED`: A chave de API não tem o escopo necessário (`403`).
* `IMAGE_NOT_FOUND`: A imagem não existe (`404`).
* `ACCESS_DENIED`: A imagem é de outra conta ou é fornecida pela plataforma, ou você é membro do workspace sem direito de reconstruí-la (`403`).
* `IMAGE_TEMPLATE_ONLY`: A imagem veio de um template e não pode ser reconstruída (`409`).
* `PLAN_REQUIRED`: O dono da imagem não tem plano ativo (`403`).
* `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`: O plano não inclui imagens Docker próprias (`403`).
* `IMAGE_BUILD_IN_PROGRESS`: A imagem já tem um build em andamento (`409`).
* `OPERATION_IN_PROGRESS`: A imagem está sendo excluída (`409`).
* `IMAGE_NOT_READY`: A imagem não tem contexto de build guardado para construir (`409`).
* `DEPLOY_RATE_LIMITED`: O limite de deploys por hora do dono da imagem foi atingido; `details` traz `limit`, `window_seconds` e `retry_after` (`429`).
* `INSTALLATION_NOT_FOUND`: O repositório vinculado não está mais em uma instalação do GitHub App do dono da imagem (`404`).
* `FETCH_ZIP_ERROR`: O GitHub não devolveu o arquivo do repositório, por exemplo porque a branch vinculada não existe mais (`404`), ou o GitHub está indisponível (`502`).
* `DOCKERFILE_NOT_FOUND`: Não há um arquivo chamado exatamente `Dockerfile` na raiz do contexto (`400`).
* `DOCKERFILE_REFUSED`: O `Dockerfile` tem uma instrução recusada; `details` lista os achados (`400`).
* `INVALID_ZIP`: O contexto de build guardado ou o arquivo do repositório não é um ZIP legível (`400`).
* `IMAGE_CONTEXT_TOO_LARGE`: O contexto de build passou de um limite: mais de 100 MB compactado, mais de 512 MB descompactado, mais de 50.000 entradas ou um `Dockerfile` maior que 1 MB (`413`).
* `IMAGE_BUILDER_UNAVAILABLE`: Nenhum host pode construir imagens agora; tente de novo mais tarde (`503`). Também é retornado quando o build não pôde ser iniciado (`409`).
* `INTERNAL_SERVER_ERROR`: Falha inesperada (`500`).

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


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