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

# Obter imagem

> Retorna uma imagem Docker personalizada pelo seu ID, com a versão atual e as aplicações que a usam.

Exige o escopo `images:read` 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 atuam sobre uma imagem que não lhes pertence.

### Resposta

**response** `object`

A imagem.

**Mostrar objeto**

**id** `string`

O ID da imagem.

**name** `string`

O nome da imagem.

**description** `string | null`

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

**owner** `string`

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

**kind** `string`

`own` para uma imagem que você criou, ou `template_copy` para a cópia da imagem de um template que [usar um template](https://docs.vertracloud.app/pt-br/templates/use/using-a-template.md) colocou na sua conta. Uma cópia ocupa um slot de imagem e só pode ser usada por meio do seu template.

**origin** `object | null`

Para um `template_copy`, o template de origem: `template_id`, `template_name` (por idioma) e `author_display` (`null` para um template da plataforma). `null` para as suas próprias imagens.

**status** `string`

Estado do build mais recente: `building`, `success` ou `failed`. Um rebuild que falha não altera a versão atual: as aplicações continuam rodando a última versão boa.

**error** `string | null`

Motivo legível do build mais recente que falhou, ou `null`.

**digest** `string | null`

Digest (`sha256:...`) da versão atual, ou `null` enquanto nenhum build teve sucesso.

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

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

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

Número de camadas da versão atual.

**suggested\_port** `integer | null`

Porta sugerida para uma nova aplicação nesta imagem: o primeiro `EXPOSE` do `Dockerfile` do contexto do build mais recente, ou `80`. `null` para uma imagem criada antes deste campo existir.

**apps** `object[]`

As aplicações criadas a partir desta imagem. Cada uma tem `id`, `name`, `version_id` (a versão da imagem que ela executa, ou `null`) e `outdated` (`true` quando a imagem tem uma versão mais nova; a aplicação passa para ela no próximo restart ou deploy que você pedir).

**github** `object | null`

O repositório e o branch do GitHub vinculados (`repository` como `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 teve sucesso.

**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": "Node 22 with our base packages",
    "owner": "account",
    "status": "success",
    "error": null,
    "digest": "sha256:3f1c0a9d5b7e2c4a8d6f1b0e9c3a7d5f2b4e6a8c0d1f3b5a7c9e2d4f6a8b0c1e",
    "uncompressed_bytes": 187432960,
    "layer_count": 9,
    "suggested_port": 3000,
    "apps": [
      {
        "id": "app-abc123def456",
        "name": "my-api-prod",
        "version_id": "imgv-111aaa222bbb",
        "outdated": false
      }
    ],
    "github": null,
    "current_version_id": "imgv-111aaa222bbb",
    "created_at": "2026-10-23T14:02:00Z",
    "updated_at": "2026-10-23T14:09: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 exigido (`403`).
* `IMAGE_NOT_FOUND`: A imagem não existe ou você não tem acesso a ela (`404`).
* `INTERNAL_SERVER_ERROR`: Falha inesperada (`500`).

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


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