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

# Atualizar domínio da aplicação

> Altera a porta, o prefixo de caminho ou o redirecionamento de um domínio personalizado, ou o torna o domínio principal, sem reiniciar a aplicação.

Altera como um domínio é servido. Envie somente os campos que quer alterar; a aplicação não é reiniciada nem recebe
um novo deploy. Exige o escopo `apps:write` quando chamado com uma chave de API.

**id** `string` *required*

O ID da aplicação.

**domain\_id** `string` *required*

O ID do domínio, obtido em [Listar domínios da aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/domains/list.md).

**workspace\_id** `string`

Se a aplicação pertencer a um workspace, o ID do workspace. Obrigatório para membros do workspace que atuam em uma aplicação que não é deles.

**port** `integer`

A porta da aplicação que atende este domínio, um inteiro de `1` a `65535`. Uma aplicação pode atender os seus domínios
em até 5 portas diferentes além da `80`.

**path\_prefix** `string | null`

Um caminho literal adicionado antes de cada requisição, no mesmo formato de
[Adicionar domínio à aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/domains/create.md) (`/api`). Envie `null` para removê-lo.

**redirect\_to** `string | null`

O ID de outro domínio da mesma aplicação para redirecionar. Envie `null` para parar de redirecionar: o domínio volta
a servir a aplicação e `redirect_status` volta para `308`. O destino não pode redirecionar para si mesmo.

**redirect\_status** `integer`

O status HTTP do redirecionamento: `301`, `302`, `307` ou `308`. Vale apenas enquanto o domínio redireciona. Quando você
define `redirect_to` sem ele, o status é `308` para um domínio que estava servindo, e permanece o mesmo para um que
já redirecionava.

**primary** `boolean`

Envie `true` em um complementar automático para torná-lo o domínio principal: ele passa a servir a aplicação,
assumindo a porta e o prefixo de caminho, e o antigo domínio principal passa a redirecionar para ele. Não tem efeito
no domínio que já é o principal, e qualquer outro domínio responde `VALIDATION_ERROR`.

### Resposta

**response** `APIApplicationDomain[]`

O domínio que você alterou e todos os outros cujo papel mudou junto com ele (por exemplo, o antigo domínio principal
após `primary`). Cada item tem os campos descritos em
[Listar domínios da aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/domains/list.md#resposta).

```json Response theme={null}
{
  "response": [
    {
      "id": "7b8f5e0a-3c1d-4e52-9a47-0d6e2c1f9b34",
      "hostname": "api.example.com",
      "apex": false,
      "companion_of": null,
      "redirect_to": null,
      "redirect_status": 308,
      "path_prefix": "/api",
      "port": 3000,
      "status": "active",
      "ssl_status": "active",
      "created_at": "2026-10-21T14:02:11.000Z"
    }
  ]
}
```

### Respostas de erro

**code** `string`

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

* `VALIDATION_ERROR`: os parâmetros de caminho ou o corpo falharam na validação, por exemplo um campo desconhecido, ou `primary` em um domínio que não pode ser trocado (`400`). A resposta também traz `message` e `path`.
* `INVALID_DOMAIN_PORT`: `port` não é um inteiro de 1 a 65535 (`400`).
* `INVALID_PATH_PREFIX`: `path_prefix` não segue o formato de [Adicionar domínio à aplicação](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/domains/create.md) (`400`).
* `INVALID_REDIRECT_TARGET`: `redirect_to` não é outro domínio desta aplicação, não está `active`, é o próprio domínio, ou criaria dois redirecionamentos encadeados (`400`).
* `AUTH_TOKEN_MISSING`, `API_KEY_INVALID`, `SESSION_REVOKED`: o cabeçalho `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada (`401`).
* `API_KEY_IP_DENIED`: a chave de API está sendo usada a partir de um IP fora da sua lista de permissões (`403`).
* `USER_NOT_FOUND`: não foi possível identificar o usuário autenticado (`401`).
* `ACCESS_DENIED`: o usuário não tem permissão para atuar na aplicação (`403`).
* `API_KEY_SCOPE_DENIED`: a chave de API não tem o escopo `apps:write` (`403`).
* `DOMAIN_PORT_LIMIT_REACHED`: a alteração faria a aplicação servir domínios em mais de 5 portas além da `80` (`403`). `details.limit` traz o limite.
* `APP_NOT_FOUND`: a aplicação especificada não existe (`404`).
* `DOMAIN_NOT_FOUND`: a aplicação não tem nenhum domínio com esse ID (`404`).
* `RATE_LIMIT_EXCEEDED`: foi atingido o orçamento de requisições da rota (`429`).
* `INTERNAL_SERVER_ERROR`: falha inesperada (`500`).

```json Error Response (400) theme={null}
{
  "code": "INVALID_REDIRECT_TARGET"
}
```

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

> [!NOTE]
>
> Esta rota tem um orçamento próprio de 20 requisições por minuto. Veja [Limite de requisições](https://docs.vertracloud.app/pt-br/api-reference/introduction.md#como-a-api-tem-limite-de-taxa).


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