> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sondercloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Domínios

> Consultando e configurando domínios customizados de uma aplicação

Toda aplicação recebe um subdomínio automático (`<domain>.sondercloud.app`) ao ser criada com o parâmetro `domain` do [upload](https://docs.sondercloud.app/sdk/aplicacoes/upload.md). Os métodos abaixo consultam esse subdomínio e gerenciam um domínio customizado apontado para ele via CNAME.

> [!NOTE]
>
> É necessário que a aplicação já tenha um subdomínio configurado antes de adicionar um domínio customizado — sem isso, `setDomain()` lança erro.

## Listar domínios da conta

Retorna todos os domínios (subdomínios e customizados) de todas as aplicações da conta autenticada, em uma única chamada.

```ts theme={null}
const domains = await sonder.apps.listDomains();
```

```json theme={null}
[
  { "appId": "8d5b4a9c-...", "domain": "minha-api.sondercloud.app", "type": "subdomain" },
  { "appId": "8d5b4a9c-...", "domain": "api.meusite.com", "type": "custom" }
]
```

> [!WARNING]
>
> Se nenhuma aplicação da conta tiver domínio configurado, a API retorna erro em vez de uma lista vazia.

## Consultar domínio de uma aplicação

```ts theme={null}
const info = await sonder.apps.getDomain(appId);
console.log(info.subdomain, info.customDomain);
```

`DomainInfo` retorna:

| Campo | Tipo | Descrição |
| - | - | - |
| `appId` | `string` | ID da aplicação. |
| `appName` | `string` | Nome da aplicação. |
| `domain` | `string \| null` | Slug do subdomínio (sem o sufixo), ex: `"minha-api"`. |
| `subdomain` | `string \| null` | Subdomínio completo, ex: `"minha-api.sondercloud.app"`. |
| `customDomain` | `string \| null` | Domínio customizado configurado, se houver. |
| `dnsRecords` | `DnsRecord[]` | Registros DNS necessários. Vazio se não houver domínio customizado. |

## Configurar um domínio customizado

```ts theme={null}
const result = await sonder.apps.setDomain(appId, 'api.meusite.com');

console.log(result.instructions);
console.log(result.dnsRecords);
```

**domain** `string` *required*

Domínio a ser apontado para a aplicação. Aceita com ou sem `http(s)://` — o SDK envia como recebido, e a API normaliza (remove protocolo e barras finais, converte para minúsculas).

`DomainSetResult` retorna o status (`"pending_verification"`), o registro CNAME a ser criado no seu provedor de DNS, e instruções em texto.

> [!WARNING]
>
> Configurar ou remover um domínio customizado reinicia a aplicação automaticamente para aplicar a mudança.

> [!NOTE]
>
> Um domínio só pode estar em uso por uma aplicação por vez — tentar reutilizar um `customDomain` já vinculado a outra aplicação retorna erro.

## Remover o domínio customizado

Remove apenas o domínio customizado; o subdomínio automático da aplicação permanece ativo.

```ts theme={null}
await sonder.apps.removeDomain(appId);
// { removed: true }
```

## Referência de métodos

| Método | Rota | Descrição |
| - | - | - |
| `apps.listDomains()` | `GET /v1/apps/domains` | Lista todos os domínios da conta. |
| `apps.getDomain(appId)` | `GET /v1/apps/:id/domain` | Consulta o domínio de uma aplicação. |
| `apps.setDomain(appId, domain)` | `POST /v1/apps/:id/domain` | Configura um domínio customizado. |
| `apps.removeDomain(appId)` | `DELETE /v1/apps/:id/domain` | Remove o domínio customizado. |

> [!NOTE]
>
> A API responde a essas quatro rotas com um envelope `{ status, code, response }`, diferente do restante da API. O SDK já desembrulha isso — os métodos acima retornam apenas o conteúdo de `response`, mantendo consistência com os demais recursos.


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