Domínio próprio

Escopo do token: domains:write (e projects:read para ler). O serviço precisa ser public.

Passos

1. Adicione o domínio ao serviço. A resposta traz as instruções de DNS e, enquanto não provado, o registro TXT de posse.
2. Crie no seu DNS o que a resposta mandar:
   • subdomínio: CNAME para cname.<APPS_DOMAIN> (o valor exato vem na resposta);
   • apex (raiz): A (e AAAA, se vier) para os IPs da plataforma;
   • TXT de posse: nome _nebular-verify.<seu-dominio>, valor nebular-verify=<token>. É obrigatório antes da primeira ativação.
   • Com Cloudflare, deixe o registro em DNS only (nuvem cinza); o proxy laranja é recusado (proxied).
3. Espere a verificação (automática; propagação de DNS pode levar minutos): consulte o domínio com backoff (2 s, dobrando até 30 s, teto de ~10 min) até status ser active.

SUF=$(date +%s)-$RANDOM
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: dom-proj-$SUF" \
  -d "{\"name\": \"demo-dom-$SUF\"}" | jq -r '.id')
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"demo-dom-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r '.id')

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: dom-add-$SUF" \
  -d "{\"hostname\": \"app-$SUF.exemplo.test\"}"

{"id": "01j9zkfgny0v4n7d9agm9tb9ht", "hostname": "app.exemplo.test", "service_id": "01j9zk3jremq8fkd3sjt7h300r", "status": "pending_dns",
 "dns": {"type": "CNAME", "name": "app.exemplo.test", "value": "cname.apps.nebularws.com"},
 "verification": {"type": "TXT", "name": "_nebular-verify.app.exemplo.test", "value": "nebular-verify=7f3a9c"},
 "created_at": "2026-10-10T12:00:00Z"}

Acompanhar até ficar ativo:

SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"demo-dom-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"demo-dom-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" -H "$H" -H "Content-Type: application/json" \
  -d "{\"hostname\": \"app-$SUF.exemplo.test\"}" | jq -r .id)

delay=2
for i in $(seq 1 20); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/domains/$D" -H "$H" | jq -r '.status')
  echo "tentativa $i: $st"
  [ "$st" = "active" ] && break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = "active" ]

Estados

status	Significado	Ação
pending_dns	ainda sem verificação, ou a verificação achou um motivo definitivo (campo error: no_records, wrong_target, proxied, txt_missing)	Crie os registros da resposta (dns e verification) e espere; veja o motivo em Problemas comuns.
verifying	a plataforma está verificando (inclusive após falha momentânea de DNS, error = dns_error)	Espere com backoff.
active	no ar; HTTPS emitido no primeiro acesso	Nada.
error	error = misconfigured: o DNS mudou e não aponta mais para a plataforma (após 3 verificações falhas seguidas); error = conflict: o domínio já está ativo em outro projeto	misconfigured: restaure os registros (volta a active sozinho). conflict: publique o TXT de posse de este domínio; com a prova, a plataforma o transfere para cá. Sem a prova, ele não é seu.

Remover

DELETE /v1/projects/{p}/services/{s}/domains/{d} (domains:write) remove o domínio; limpe também os registros DNS.

Se algo falhar

Resposta	O que fazer
409 domain_taken	Domínio já adicionado ao time ou ativo em outro projeto: use a prova TXT (acima).
400 invalid_request	Nome de domínio inválido. Corrija.
limite de domínios do projeto	Remova um domínio ou peça aumento (veja Limites e cotas).
404 not_found	Projeto, serviço ou domínio inexistente ou de outro time.
429 rate_limited	Espere Retry-After.

Veja também TLS e Erros.