Reconstruir imagem da fonte atual

POST

images

{image_id}

rebuild

curl --request POST \
  --url https://api.vertracloud.app/v1/images/{image_id}/rebuild \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/images/{image_id}/rebuild', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/images/{image_id}/rebuild"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

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. 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. Precisa do escopo images:write quando chamada com uma chave de API.

string

required

O ID da imagem.

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

object

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

Show Mostrar objeto

string

O ID da imagem.

string

O nome da imagem.

string | null

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

string

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

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.

string | null

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

string | null

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

integer | null

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

integer | null

Número de camadas da versão atual.

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

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.

string | null

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

string

Quando a imagem foi criada.

string

Quando a imagem foi atualizada pela última vez.

{
  "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

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

{
  "code": "IMAGE_BUILD_IN_PROGRESS"
}

Last modified on November 11, 2026

Reconstruir imagem da fonte atual

curl --request POST \
  --url https://api.vertracloud.app/v1/images/{image_id}/rebuild \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/images/{image_id}/rebuild', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/images/{image_id}/rebuild"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

Introduction

Deploy

Troubleshooting

Reconstruir imagem da fonte atual

Resposta

Respostas de erro

​Resposta

​Respostas de erro

Resposta

Respostas de erro