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

# Detalhes da aplicação

> Retorna as informações detalhadas de uma aplicação pelo seu ID.

**id** `string` *required*

O ID da aplicação cujos detalhes serão retornados. Se a aplicação pertencer a um workspace, informe o ID dele no query parameter `workspace_id`.

**workspace\_id** `string`

Se a aplicação pertencer a um workspace, o ID do workspace. Obrigatório para membros do workspace que agem sobre uma aplicação que não lhes pertence.

### Resposta

**response** `object`

Os detalhes da aplicação.

**Mostrar objeto**

**id** `string`

O ID da aplicação.

**cluster** `integer`

O ID do cluster da aplicação.

**type** `integer`

O tipo da aplicação.

**name** `string`

O nome da aplicação.

**description** `string`

A descrição da aplicação.

**owner\_id** `string`

O ID do dono da aplicação.

**owner\_plan** `string | null`

O nome do plano do dono (por exemplo, `pro` ou `enterprise-8`), ou `null` quando o dono não tem plano.

**language** `string`

A linguagem de programação da aplicação (por exemplo, `javascript`).

**ram** `integer`

A RAM da aplicação, em MB.

**status** `string`

O status da aplicação: `up`, `down` ou `building` (criação em andamento; a maioria das ações responde `409 APP_BUILDING`).

**last\_build\_error** `string | null`

O código da última falha de build ou de instalação, ou `null` após um build bem-sucedido. Um dos valores
`BUILD_FAILED`, `BUILD_TIMEOUT`, `BUILD_INTERRUPTED`, `INSTALL_FAILED`, `INSTALL_OUT_OF_MEMORY`,
`INSTALL_TIMEOUT` ou `INSTALL_SHIELD_BLOCKED`. O detalhe está nos logs da aplicação; veja em
[Erros](https://docs.vertracloud.app/pt-br/api-reference/errors.md#códigos-de-falha-de-build) o que fazer para cada código.

**subdomain** `string | null`

O subdomínio da aplicação, quando aplicável.

**domains** `APIApplicationDomain[]`

Os domínios personalizados da aplicação, com status, situação do SSL, porta, prefixo de caminho e redirecionamento. Vazio quando não há nenhum.
Cada item está descrito em [Listar domínios da aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/domains/list.md#resposta).

**public\_url** `string | null`

A URL pública canônica da aplicação, já calculada pelo servidor: o domínio personalizado principal
quando existe, caso contrário o `subdomain` (`null` quando a aplicação não tem nenhum dos dois, ou seja, não é publicada na web). Monte
links a partir deste campo, nunca diretamente de `subdomain` — uma implantação self-hosted atrás de uma
borda com configuração não padrão pode retornar outro host ou outro esquema aqui.

**last\_snapshot** `string | null`

O timestamp do último snapshot da aplicação.

**main\_file** `string`

O arquivo principal da aplicação.

**version** `string`

A versão do runtime (por exemplo, `recommended` ou `latest`).

**start\_command** `string | null`

O comando de inicialização da aplicação, se especificado.

**build\_command** `string | null`

O comando de build, se especificado. Roda após a instalação das dependências e antes de a
aplicação iniciar, em um ambiente de build isolado. `null` quando nenhum comando de build está definido.

**offline\_since** `string | null`

O timestamp desde quando a aplicação está offline, se aplicável.

**shield\_cooldown** `object | null`

Presente enquanto a Vertra Shield pausou a aplicação. Inclui `until` (o fim do cooldown),
`reason` (`burst` ou `rate_limit`) e `direction` (`in` ou `out`); `null` quando nenhum cooldown está ativo.

**github** `object | null`

O repositório GitHub vinculado (`repo_owner`, `repo_name`) quando o deploy automático está conectado; `null`
quando a aplicação foi criada a partir de um zip ou de um snapshot. A URL do webhook não é incluída — use
`GET /v1/apps/{id}/deploys/webhook` para obtê-la.

**custom\_image** `object | null`

A imagem Docker personalizada da qual a aplicação roda; `null` para uma aplicação comum. Com uma imagem, `language`, `version`, `main_file`, `start_command` e `build_command` não se aplicam: eles vêm da imagem. Veja [Imagens Docker personalizadas](https://docs.vertracloud.app/pt-br/guides/custom-docker-images.md).

**Propriedades de custom\_image**

**image\_id** `string`

O ID da imagem. O `id` e o `name` deste objeto são os da aplicação, não os da imagem.

**port** `integer | null`

A porta em que a aplicação escuta e para a qual a plataforma encaminha o tráfego; `null` para uma aplicação sem tráfego web.

**version\_id** `string | null`

A versão da imagem que a aplicação roda, ou `null` quando ela ainda não iniciou em nenhuma versão.

**outdated** `boolean`

`true` quando a imagem tem uma versão mais nova do que a que a aplicação roda. Ela passa para a nova versão no próximo restart ou deploy que você pedir.

**template** `object | null`

De onde veio a aplicação, quando ela foi criada a partir de um [template](https://docs.vertracloud.app/pt-br/templates/use/using-a-template.md), ou `null` para uma aplicação comum.

**Propriedades de template**

**template\_id** `string`

O ID do template.

**slug** `string`

O slug do template.

**name** `object`

O nome do template por idioma: `pt-br`, e `en` e `es` quando traduzido.

**icon\_url** `string | null`

A URL estável do ícone do template, ou `null` para um template privado sem ícone ou para um template que foi removido.

**origin** `string`

`vertra`, `community` ou `private`.

**version\_id** `string`

O ID da versão a partir da qual a aplicação foi criada ou para a qual foi atualizada por último.

**version** `string`

O número dessa versão.

**closed** `boolean`

`true` quando o template está fechado: o código da aplicação não fica acessível.

**detached** `boolean`

`true` quando a aplicação saiu do template e não recebe mais versões.

**update\_available** `boolean`

`true` quando o template tem uma versão mais nova para a qual a aplicação pode ser atualizada.

**latest\_version** `string | null`

O número da versão mais nova, ou `null` quando não há nenhuma.

**removed** `boolean`

`true` quando o autor removeu o template; a aplicação continua rodando, mas não recebe mais atualizações.

**via\_share\_link** `boolean`

`true` quando a aplicação foi criada a partir de um link de compartilhamento.

**service\_id** `string | null`

O ID do serviço do template que esta aplicação representa, ou `null` quando o template tem um único serviço.

**permissions** `object`

O que o template permite fazer com esta aplicação: `code_view`, `code_edit`, `ram_change`, `ram_below_min`, `ram_above_max`, `env_add`, `commands_edit`, `terminal`, `save_as_template` e `detach`, todos booleanos.

**locked\_deploy\_settings** `string[]`

As configurações de deploy que o template trava para esta aplicação: `zero_downtime` e/ou `auto_rollback`. Mudá-las para outro valor em [`PATCH /v1/apps/:id/config`](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/updateconfig) devolve `403 TEMPLATE_SETTING_LOCKED`. Vazio quando a aplicação está desvinculada.

**stack\_id** `string | null`

O ID da [stack](https://docs.vertracloud.app/pt-br/api-reference/endpoint/stacks/get.md) à qual a aplicação pertence, ou `null` quando ela não faz parte de uma stack.

**stack\_service\_key** `string | null`

O ID do serviço do template que esta aplicação representa dentro da stack, ou `null` quando você a adicionou por conta própria.

**deploy** `object`

Como um deploy substitui a versão em execução e o que acontece se ele falhar.

**Propriedades de deploy**

**zero\_downtime** `string`

A opção salva: `off` (o padrão), `auto` ou `on`. Altere-a com [Atualizar configuração da aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/updateconfig.md).

**zero\_downtime\_active** `boolean`

O que vale para o próximo restart ou deploy: `true` no Enterprise quando `zero_downtime` está em `on`, ou quando está em `auto` e a aplicação recebe tráfego web.

**auto\_rollback** `boolean`

A opção salva, `false` por padrão. Ela devolve o valor salvo em qualquer plano, mas só passa a valer a partir do Intermediary.

**health\_check\_path** `string | null`

O caminho HTTP chamado em uma nova versão para verificar se ela está saudável. `null` significa `/`.

**created\_at** `string`

O timestamp de quando a aplicação foi criada.

**updated\_at** `string`

O timestamp de quando a aplicação foi atualizada pela última vez.

```json Response theme={null}
{
  "response": {
    "id": "app-abc123def456",
    "cluster": 1,
    "type": 1,
    "name": "API Simples",
    "description": "I have a description :)",
    "owner_id": "user-123456789012345678",
    "owner_plan": "pro",
    "language": "javascript",
    "ram": 128,
    "status": "up",
    "subdomain": "myapp.vertraweb.app",
    "domains": [],
    "public_url": "https://myapp.vertraweb.app",
    "last_snapshot": "2026-03-09T15:51:47.234Z",
    "main_file": "index.js",
    "version": "recommended",
    "start_command": "node index.js",
    "build_command": null,
    "offline_since": null,
    "shield_cooldown": null,
    "github": null,
    "custom_image": null,
    "deploy": {
      "zero_downtime": "off",
      "zero_downtime_active": false,
      "auto_rollback": false,
      "health_check_path": null
    },
    "created_at": "2026-03-09T15:51:47.234Z",
    "updated_at": "2026-03-20T15:06:41.449Z"
  }
}
```

### Respostas de erro

**code** `string`

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

* `AUTH_TOKEN_MISSING`, `API_KEY_INVALID`, `SESSION_REVOKED`: o header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada (`401`).
* `API_KEY_IP_DENIED`, `API_KEY_SCOPE_DENIED`: a chave de API é usada a partir de um IP fora da sua allowlist, ou não tem o escopo que a rota exige (`403`).
* `ACCESS_DENIED`: o recurso pertence a outra conta, ou você não tem a permissão do workspace para ele (`403`).
* `APP_NOT_FOUND`: a aplicação informada não existe.

**message** `string`

Uma mensagem descritiva com detalhes adicionais sobre o erro.

```json Error Response (404) theme={null}
{
  "code": "APP_NOT_FOUND"
}
```

```json Error Response (403) theme={null}
{
  "code": "ACCESS_DENIED"
}
```


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