# Nebular — documentação completa (texto puro)

Fonte: https://docs.nebularws.com. Ordem: tutorial (começar, guias, referência).

---

URL: https://docs.nebularws.com/index.md

# Nebular Docs

A Nebular é uma plataforma de hospedagem. Esta documentação é escrita para **pessoas e para agents de IA**: cada página existe também em Markdown cru (acrescente `.md` à URL) e todo o conteúdo está em texto puro em [`/llms-full.txt`](/llms-full.txt).

## Usar com um agent

1. Crie um [token de API](/comecar/token/) (`nbk_…`).
2. Cole no agent o conteúdo de `https://docs.nebularws.com/llms-full.txt` (ou aponte para `https://docs.nebularws.com/llms.txt`) e o token como segredo do ambiente, nunca no texto do prompt.
3. Peça a tarefa. Veja [Como um agent usa isto](/comecar/como-um-agent-usa-isto/) e [Para agents](/agents/).

## O que a API cobre

A API pública `/v1` cobre **projetos, serviços, deploys, variáveis com referência, rede privada, volumes, bancos, domínios, templates (WordPress), galerias e arquivos**. Os guias descrevem o contrato v13; páginas ainda marcadas “em construção” (referência gerada de rotas, isolamento) não têm API publicada: não invente rotas.

## Mapa

| Área | Conteúdo | Estado |
|---|---|---|
| [Começar](/comecar/token/) | token, conceitos, convenções da API | real |
| [CDN e imagens](/cdn/visao-geral/) | galerias, arquivos, transformação, cache | real |
| [Erros](/erros/tabela/) | código, HTTP, causa e ação do agent | real |
| [Segurança](/seguranca/tokens-e-escopos/) | tokens, escopos, abuso | parcial |
| [Operação](/operacao/limites-e-cotas/) | limites e cotas, [como escrever um app pronto para escalar](/operacao/app-pronto-para-escalar/) | parcial |
| [Referência da API](/referencia/autenticacao/) | gerada da OpenAPI | parcial |
| [Guias por stack](/guia/go/), [bancos](/bancos/postgres/), [domínios](/dominios/dominio-proprio/), [receitas](/receitas/do-zero-ao-ar-com-um-agent/) | deploy ponta a ponta | real (contrato v13) |

---

URL: https://docs.nebularws.com/comecar/token.md

# Token de API

Para usar a API `/v1` você precisa de um **token de API** (`nbk_…`). Ele pertence ao time, não a uma pessoa.

## Criar o token

1. No painel: **Time → Configurações → Tokens de API → Criar token**. Exige papel `admin` do time e confirmação
   recente de identidade (step-up).
2. Escolha o nome, os **escopos** e, opcionalmente, as galerias permitidas (por padrão, todas as do time):

   | Escopo | Permite |
   |---|---|
   | `assets:read` | listar galerias e arquivos, consultar detalhes e status de varredura |
   | `assets:write` | enviar, versionar e excluir arquivos |
   | `galleries:manage` | criar galerias (um token restrito a galerias específicas **não** cria galeria: 403) |

   Escopos de deploy, serviços, variáveis, domínios, volumes, bancos, logs e templates:

   | Escopo | Permite |
   |---|---|
   | `projects:read` | listar e ler projetos, serviços, deploys, domínios e bancos |
   | `projects:write` | criar, editar e apagar projetos e serviços |
   | `deploy` | disparar deploy e rollback, enviar fonte |
   | `env:read` | ler nomes e valores **não sensíveis** de variáveis |
   | `env:write` | criar, alterar e apagar variáveis |
   | `env:reveal` | ver valores sensíveis (o token precisa ter sido criado com step-up **e** com este escopo explícito) |
   | `domains:write` | anexar e remover domínios |
   | `volumes:write` | criar e apagar volume |
   | `databases:write` | criar, apagar, rotacionar credencial, backup e restore de bancos |
   | `logs:read` | ler logs de build e de runtime |
   | `templates:deploy` | instanciar templates (ex.: WordPress) |

   Um token também pode ser restrito a projetos específicos (`project_ids`). Detalhes em [Tokens e escopos](/seguranca/tokens-e-escopos/).

3. **O token (`nbk_…`) é mostrado uma única vez.** Guardamos só o hash. Perdeu? Revogue e crie outro.
4. Validade: 90 dias por padrão, máximo 1 ano. O token pertence ao **time** (não a uma pessoa) e nunca dá acesso a
   membros ou cobrança. Pode ser revogado a qualquer momento.
5. Envie **somente** no cabeçalho `Authorization: Bearer nbk_…`. **Nunca em query string** (a requisição é
   recusada com 401). **Cookies são ignorados** nestas rotas.

Variáveis usadas nos exemplos:

```bash
export NEBULAR_API=https://api.nebularws.com   # base URL
export NEBULAR_TOKEN=nbk_...                   # o seu token
export GALLERY=marcas-k7p2                     # a "key" de uma galeria (veja [Galerias e arquivos](/cdn/galerias/))
```

Todas as rotas ficam em `/v1` e o corpo de erro tem sempre o formato `{"error": "<codigo>", "message": "..."}`:
trate pelo `error` (estável), mostre o `message` (pt-BR) para pessoas.

## Verificação

Confirme o token e veja seus escopos e limites com `GET /v1/me` (espera `200`):

```bash
curl -sS "$NEBULAR_API/v1/me" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"team": {"id": "01j9zk8xwdtry8pxzy0qqvb8k3", "name": "Acme", "plan": "hobby"},
 "token": {"id": "01j9zksf51s25jd7735q8fefyf", "name": "agente-deploy", "scopes": ["projects:read", "projects:write", "deploy"], "project_ids": null, "expires_at": "2026-11-10T12:00:00Z"}}
```

A resposta traz o time (`team`: `id`, `name`, `plan`) e o token (`token`: `id`, `name`, `scopes`, `project_ids` — `null` quando vale para todos os projetos — e `expires_at`). Os limites do time estão em `GET /v1/limits`.

Ou, só para galerias, listando as galerias do time (espera `200`):

```bash
curl -sS "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401 unauthorized` | Token ausente, expirado, revogado ou enviado fora do cabeçalho. Não repita: confira o cabeçalho ou peça um token novo a um admin. |
| `403 forbidden` | O token não tem o escopo da rota. Peça um token com o escopo certo. |

Veja a [tabela completa de erros](/erros/tabela/) e [Tokens e escopos](/seguranca/tokens-e-escopos/).

---

URL: https://docs.nebularws.com/comecar/conceitos.md

# Conceitos

## Visão geral

```mermaid
flowchart LR
  T[Time] --> K[Token nbk_]
  T --> PR[Projeto = grupo]
  PR --> SV[Serviço app]
  PR --> DB[Serviço database]
  PR --> SH[Variáveis shared]
  SV --> VAR[Variáveis]
  SV --> VOL[Volume]
  SV --> DOM[Domínio]
  SV --> DEP[Deploy]
  T --> G[Galeria]
  G --> A[Arquivo]
```

## Time e token

- **Time**: dono dos recursos e dos tokens. Um token pertence ao time, nunca a uma pessoa.
- **Token de API** (`nbk_…`): credencial com **escopos** e, opcionalmente, restrita a alguns projetos (`project_ids`) ou galerias. Veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/).

## Projeto (grupo)

Um **projeto** é um grupo de serviços. Todos os serviços do projeto ficam numa **rede privada** própria (nunca alcançam outro projeto) e têm em comum as **variáveis `shared`** do projeto, que cada serviço usa referenciando-as com `${{shared.NOME}}` (não entram sozinhas). Veja [Rede privada](/conectados/rede-privada/).

## Serviço

Um **serviço** pertence a um projeto. Campos principais:

| Campo | Significado |
|---|---|
| `name` | `^[a-z][a-z0-9-]{0,30}$`, único no projeto; é o hostname na rede privada. Imutável. |
| `kind` | `app` (seu código ou imagem) ou `database` (criado pela rota de bancos). Imutável. |
| `visibility` | `public` (recebe `slug` e URL pública) ou `private` (só na rede do projeto, sem rota pública). **Se omitida, o padrão é `private`**: informe `public` e um `slug` para ter URL. |
| `source` | `{"type":"upload"}`, `{"type":"git","installation_id","repo","branch","root_dir","watch_paths"}` ou `{"type":"image","ref"}`, com `ref` = `repo[:tag]@sha256:<digest>` para fixar a versão ([Imagem pública](/guia/imagem-publica/#fixar-por-digest-e-como-obter-o-digest)). |
| `build` | `{"builder":"auto\|node\|go\|rust\|python\|static\|dockerfile","dockerfile_path":"Dockerfile"}`. |
| `port` | porta interna (padrão 3000). |
| `healthcheck_path`, `start_command`, `build_command` | opcionais. |
| `resources` (`memory_mb`, `cpus`) | recursos (padrão 512 MB e 0.5 CPU; máximo por plano). Veja [Escala e recursos](/operacao/escala-e-recursos/). |
| `auto_deploy` | deploy automático por git. |

Todo serviço roda como não-root, com sistema de arquivos somente leitura (só `/tmp` e o volume são graváveis). Veja [Isolamento](/seguranca/isolamento/).

### O serviço `web` padrão

Todo projeto novo nasce com um serviço `web` (`kind=app`, fonte `upload`, `build.builder=auto`, porta 3000). Ele nasce **`public`**, já com `slug` e `public_url` gerados (por exemplo `web-br5pg0` e `https://web-br5pg0.<dominio-de-apps>`), mesmo que o padrão de `visibility` ao criar outros serviços seja `private`. Use `PATCH .../services/web` para adaptá-lo (fonte, build, porta) em vez de criar outro; um `POST` com `name: "web"` dá `409 name_taken`.

Para torná-lo privado: `PATCH .../services/web` com `{"visibility": "private"}`. O `slug` e a `public_url` desaparecem e ele passa a ser alcançável só na rede do projeto. Voltando a `public` sem informar `slug`, a plataforma deriva um do nome.

```bash
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"web-padrao-$(date +%s)-$RANDOM\"}" | jq -r .id)
# o web padrão nasce público, com slug e public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "Authorization: Bearer $NEBULAR_TOKEN" \
  | jq -e '.items[] | select(.name == "web") | .visibility == "public" and (.slug | length) > 0 and (.public_url | length) > 0' >/dev/null
# tornar privado
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"visibility": "private"}'
```

## Variáveis e referências

Variável: escopo `service` (só aquele serviço) ou `shared` (guardada no projeto; só chega ao serviço que a referencia com `${{shared.NOME}}`). O valor pode referenciar outro serviço com `${{servico.VAR}}` ou o grupo com `${{shared.VAR}}`; a resolução acontece no deploy. Veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

## Volume

Disco persistente de um serviço (1 a 50 GB, 1 por serviço), montado em um caminho absoluto; sobrevive a redeploy. Veja [Volumes](/conectados/volumes/).

## Banco

Serviço `kind=database` com motor `postgres`, `mariadb` ou `sqlite`, num nó de banco gerenciado. Entrega variáveis prontas (`DATABASE_URL` etc.) para referenciar. Veja [PostgreSQL](/bancos/postgres/), [MariaDB](/bancos/mariadb/), [SQLite](/bancos/sqlite/).

## Domínio

Todo serviço público tem um subdomínio gerado; você pode anexar domínio próprio. Veja [Subdomínio gerado](/dominios/subdominio-gerado/) e [Domínio próprio](/dominios/dominio-proprio/).

## Deploy

Um **deploy** constrói e sobe uma versão de um serviço (ou do grupo inteiro, em ordem topológica das referências). Estados: `queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `canceled`, `superseded`. O agent acompanha por polling com backoff. Veja [Deploys e status](/operacao/deploys-e-status/).

## Galeria e arquivo (CDN)

- **Galeria**: pasta de arquivos do time servida pela CDN, com `key` pública e imutável.
- **Arquivo** (asset): um nome dentro de uma galeria; enviar o mesmo nome cria uma **versão**.
- **URL imutável** e **URL alias**: veja [Visão geral da CDN](/cdn/visao-geral/).
- **Varredura**: todo arquivo é varrido antes de publicar: [Classes de arquivo e varredura](/cdn/classes-de-arquivo-e-varredura/).

---

URL: https://docs.nebularws.com/comecar/primeiro-deploy.md

# Primeiro deploy

Este é o fluxo base de todos os [guias por stack](/guia/nodejs-next/). Escopos do token: `projects:write`, `deploy`, `projects:read` (veja [Token de API](/comecar/token/)). Todo `POST` que cria leva `Idempotency-Key`; repetir a mesma chave com o mesmo corpo devolve a mesma resposta.

Cada bloco abaixo é autossuficiente (variáveis `P` = id do projeto, `S` = id do serviço, `D` = id do deploy).

## 1. Criar o projeto

Um projeto é um grupo de serviços que compartilham rede e podem compartilhar variáveis por referência ([Conceitos](/comecar/conceitos/)).

```bash
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pd-proj-$(date +%s)-$RANDOM" \
  -d "{\"name\": \"meu-app-$(date +%s)-$RANDOM\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "meu-app-1760000000"}
```

Guarde `id` (`P`). Em erro:

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido. Pare e confira o cabeçalho. |
| `403 forbidden` | Falta o escopo `projects:write`. Peça um token novo. |
| `409` (ex.: `slug_taken`, `project_quota_exceeded`) | Troque o nome ou apague um projeto que não usa mais. |

## 2. Criar o serviço

Duas fontes (`source`) cobrem o primeiro deploy: **imagem pública** ou **upload** de código. Para `visibility: "public"` informe o `slug` (sai em `https://<slug>.<domínio de apps>`); omitido, a plataforma deriva um do nome. O `web` que todo projeto traz nasce **público**, já com `slug` e `public_url` (para privado: `PATCH` com `{"visibility": "private"}`; veja [Conceitos](/comecar/conceitos/#o-serviço-web-padrão)).

### Opção A: imagem pública

```bash
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: pd-proj2-$SUF" -d "{\"name\": \"meu-app-$SUF\"}" | jq -r .id)
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\": \"meu-app-$SUF\",
    \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }"
```
```json
{"id": "01j9zk3jremq8fkd3sjt7h300r", "name": "web", "kind": "app", "visibility": "public", "port": 8080}
```

### Opção B: upload de código

Use `"source": {"type": "upload"}` e um `build` (`builder` = `auto`, `node`, `go`, `rust`, `python`, `static` ou `dockerfile`). Sem `build`, vale `auto`.

```bash
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: pd-proj3-$SUF" -d "{\"name\": \"meu-site-$SUF\"}" | jq -r .id)
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\": \"meu-site-$SUF\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"auto\"}
  }"
```
```json
{"id": "01j9zkngmvzxkw57zdyzz80b5e", "name": "web", "kind": "app", "visibility": "public", "port": 3000}
```

Regras do `name`: `^[a-z][a-z0-9-]{0,30}$`, único no projeto (é o hostname na [rede privada](/conectados/rede-privada/)). `port` padrão: 3000.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | `name`, `source.type`, `build.builder` ou `healthcheck_path` inválidos: corrija o campo citado em `message`. |
| `404 not_found` | O projeto não existe ou não é do seu time (as duas situações são indistinguíveis). |
| `409 name_taken` / `slug_taken` | `name` ou `slug` já usado (todo projeto já nasce com um serviço `web`: use `PATCH` nele ou escolha outro nome). Troque. |

## 3. Disparar o deploy

Resposta imediata: o deploy fica `queued` e o build roda em seguida. Guarde o `id` (`D`).

```bash
# preparo (passos 1 e 2): projeto e serviço de imagem
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\": \"pd4-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pd-dep-$SUF" \
  -d '{}'
```
```json
{"id": "01j9zkv1t9ndd76xmr8ahxee7p", "status": "queued"}
```

Com `source.type = "upload"`, envie o código como `multipart/form-data` nesta mesma rota (no lugar do corpo `{}`): `-F "file=@fonte.tar.gz"`. Com `git`, o deploy usa o repositório e o branch do `source`.

| Resposta | O que fazer |
|---|---|
| `403 forbidden` | Falta o escopo `deploy`. |
| `409 deploy_in_progress` | Já existe um deploy em andamento para o serviço: consulte-o em vez de disparar outro. |
| `unresolved_reference` / `reference_cycle` | Variável referenciada não existe ou há ciclo: veja [Variáveis e referências](/conectados/variaveis-e-referencias/). |
| `429` | Espere `Retry-After` ([Rate limit e retry](/erros/rate-limit-e-retry/)). |

## 4. Esperar o deploy (polling com backoff)

Não há webhooks neste ciclo. Consulte `GET .../deployments/{d}` começando em 2 s e dobrando até 30 s, por no máximo cerca de 10 minutos. Terminal de sucesso: `ready`. Terminais de falha: `failed`, `blocked`, `canceled`, `superseded`.

```bash
# preparo (passos 1 a 3): projeto, serviço de imagem e deploy
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\": \"pd5-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]
```

Em `failed`, leia o [log de build](/operacao/logs/). Em `blocked`, um serviço do qual este depende falhou ([Deploys e status](/operacao/deploys-e-status/)). Em `superseded`, um deploy mais novo tomou o lugar: acompanhe o mais novo.

## 5. Verificar a URL pública

Com `ready`, o serviço público responde em `https://<slug>.<domínio de apps>`, onde `<slug>` é o que você enviou na criação.

```bash
curl -sS -o /dev/null -w '%{http_code}\n' "https://meu-app-1760000000.nebularws.com/healthz"
```

Se não for `200`, leia os [logs de runtime](/operacao/logs/); para voltar à versão anterior, [rollback](/operacao/rollback/). Para domínio próprio, [Domínio próprio](/dominios/dominio-proprio/).

## Listar o que você criou

```bash
curl -sS "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"items": [{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "meu-app-1760000000"}], "next_cursor": null, "has_more": false}
```

---

URL: https://docs.nebularws.com/comecar/como-um-agent-usa-isto.md

# Como um agent usa isto

Um agent usa a API `/v1` em um laço simples:

1. **Autenticar**: `Authorization: Bearer $NEBULAR_TOKEN`. O token vem de variável de ambiente, nunca do texto do prompt nem de arquivo versionado. Confirme escopos e limites com `GET /v1/me` ([Token de API](/comecar/token/)).
2. **Agir** com `Idempotency-Key` em todo `POST` que cria, para que repetir seja seguro.
3. **Esperar** quando a resposta for assíncrona: upload `202 pending` ([Uploads pending](/cdn/galerias/#uploads-pending-202-como-esperar)) ou deploy `queued`. Consulte o recurso com backoff (2 s, dobrando até 30 s); não reenvie.
4. **Ler o erro** pelo campo `error` e decidir pela [tabela de erros](/erros/tabela/):
   - `4xx` (exceto `429`): corrija a requisição; não repita igual.
   - `429`, `503`: repita depois de `Retry-After` (ou com backoff).
   - `401`/`403`: pare e peça um token novo ou com o escopo certo a uma pessoa.
   - `404`: o recurso não existe **ou não é do seu time**; a API não distingue. Confira o id; não tente descobrir.
5. **Parar e pedir uma pessoa** quando o erro exigir decisão humana (`malware_detected`, `quota_exceeded`, deploy `failed` sem causa clara nos logs).

## Laço de deploy

1. `POST /v1/projects` e `POST .../services` (veja [Primeiro deploy](/comecar/primeiro-deploy/)).
2. Variáveis e, se preciso, banco e volume ([Variáveis e referências](/conectados/variaveis-e-referencias/), [PostgreSQL](/bancos/postgres/)).
3. `POST .../deployments` (ou `POST /v1/projects/{p}/deploy` para o grupo).
4. Polling de `GET .../deployments/{d}` até `ready` (para o grupo, `GET /v1/projects/{p}/group-deployments/{g}` até `status` sair de `running`; `ready` é sucesso). Estado `failed`, `blocked`, `canceled` ou `superseded`: pare e leia o log de build ([Logs](/operacao/logs/)).
5. Verifique a URL pública. Se falhar, [rollback](/operacao/rollback/) para o deploy anterior e reporte.

Fluxo de decisão completo: [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/). Receita pronta: [Do zero ao ar com um agent](/receitas/do-zero-ao-ar-com-um-agent/).

---

URL: https://docs.nebularws.com/comecar/convencoes-da-api.md

# Convenções da API

- **Base URL**: `https://api.nebularws.com`; todas as rotas ficam em `/v1`.
- **Autenticação**: `Authorization: Bearer nbk_…`, nunca em query string. Cookies são ignorados. Veja [Token de API](/comecar/token/).
- **Erros**: sempre `{"error": "<codigo>", "message": "..."}`. Trate pelo `error` (estável); mostre o `message` (pt-BR) a pessoas. Veja a [tabela de erros](/erros/tabela/).
- **404 anti-IDOR**: recurso inexistente e recurso de outro time/projeto respondem igual (`404 not_found`). `401` é genérico de propósito. `403` só aparece quando o recurso é seu e falta escopo. Não tente distinguir.
- **Paginação por cursor**: listas devolvem `items`, `next_cursor` e `has_more`. Siga `next_cursor` enquanto `has_more` for `true`; o cursor é opaco. Receita em [Galerias e arquivos](/cdn/galerias/#d-listar-com-cursor-next_cursor--has_more).
- **Idempotência**: todo `POST` que cria ou dispara aceita `Idempotency-Key` (8 a 128 caracteres `[A-Za-z0-9._:-]`). Mesma chave e mesmo pedido em 24 h devolve a mesma resposta (cabeçalho `Idempotent-Replay: true`); mesma chave com outro pedido dá `422 idempotency_conflict` (`409` no upload de galeria); chave malformada (fora de 8 a 128 caracteres `[A-Za-z0-9._:-]`), `400 invalid_request`. Só respostas `2xx` são gravadas. Veja [Galerias e arquivos](/cdn/galerias/#idempotência-idempotency-key).
- **Corpo JSON**: todo `POST`/`PUT`/`PATCH` **com corpo** leva `Content-Type: application/json`. Regra exata para `POST /v1/projects/{p}/deploy`, `POST .../services/{s}/deployments` e `POST .../deployments/{d}/rollback`: o corpo é **opcional**. Sem corpo (ou `Content-Length: 0`), com ou sem `Content-Type`, vale `{}`; com corpo, ele tem de ser JSON com `Content-Type: application/json` (outro tipo, como `text/plain` ou formulário, dá `415 unsupported_media_type`); o deploy de serviço aceita também `multipart/form-data` (campo `file`). Os exemplos mandam `Content-Type: application/json` e `{}` por ser a forma que funciona em qualquer cliente HTTP. Todo projeto nasce com um serviço `web` padrão, **público** e com `slug` ([Conceitos](/comecar/conceitos/#o-serviço-web-padrão)).
- **Rate limit**: por token e por IP; em `429` espere `Retry-After` segundos. Veja [Rate limit e retry](/erros/rate-limit-e-retry/).
- **Ids**: opacos. Projetos, serviços, deploys, bancos e demais recursos da v13 usam ULID em minúsculas de 26 caracteres (por exemplo `01m4kxaxjts58n5esjajbr5pg0`); galerias e arquivos têm prefixo do tipo (`gal_…`, `ast_…`, `ver_…`). Não os interprete nem dependa do formato: use o que a API devolveu.
- **Datas**: RFC 3339 em UTC (`2026-10-09T14:03:11Z`).
- **Assíncrono**: deploys, backups e restores respondem logo e terminam depois; consulte o recurso com backoff. Não há webhooks neste ciclo.
- **Estados de deploy**: `queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `canceled`, `superseded`. Terminais: todos menos `queued`, `building` e `deploying`. Veja [Deploys e status](/operacao/deploys-e-status/).
- **Limites do token e do time**: `GET /v1/me` e `GET /v1/limits`.

---

URL: https://docs.nebularws.com/guia/nodejs-next.md

# Node.js e Next.js

Serviços Node (Express, Fastify, Nest, Next.js) rodam `npm start` como usuário não-root (`node`, uid 1000) em Node 24 com `NODE_ENV=production`.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

Com `builder: "auto"` (ou `"node"`) a Nebular lê o `package.json` (um `Dockerfile`, se existir, vence):

- **Com `scripts.start`**: servidor Node. O build roda `npm ci` (se houver `package-lock.json`, senão `npm install`), `npm run build --if-present`, remove devDependencies (`npm prune --omit=dev`) e copia a árvore para `/app`. O start é `npm start`.
- **Sem `scripts.start`**: site estático (veja [Site estático](/guia/site-estatico/)).
- `build_command` substitui o `npm run build`; `start_command` substitui o `npm start`.
- Porta: 3000 por padrão. O app **tem que** escutar `0.0.0.0:$PORT`. Servidores `vite preview`/`astro preview` ignoram `PORT`: a plataforma acrescenta `--host 0.0.0.0 --port 3000` ao `npm start` nesses casos.
- Next.js: use `"start": "next start"` (escuta `PORT`; defina `HOSTNAME=0.0.0.0` como variável do serviço se o app só responder dentro do container). O sistema de arquivos é somente leitura, mas a plataforma concede um tmpfs em `.next/cache` para o cache de ISR/fetch. Não grave outros arquivos em runtime.
- **Piso de segurança:** tudo que começa com `NEXT_PUBLIC_` é embutido no bundle do browser em tempo de build. Nunca ponha segredo nessas variáveis; segredo só em variáveis lidas no servidor.

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```json
{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}
```

```ts
// app/healthz/route.ts: health check do Next (App Router)
export function GET() {
  return new Response("ok");
}
```

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="app-next-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "app-next-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `node`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="app-next-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"node\"},
    \"port\": 3000,
    \"healthcheck_path\": \"/healthz\"
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 3000}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="app-next-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"node\"},
    \"port\": 3000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/HOSTNAME" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "0.0.0.0"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `node_modules`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="app-next-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"node\"},
    \"port\": 3000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| deploy `ready` mas o health check falha / 502 | O app não escuta `0.0.0.0:$PORT`. Confira `PORT`, `HOSTNAME` e o `port` do serviço. |
| `failed` no `npm ci` | `package-lock.json` fora de sincronia com `package.json`: regere o lockfile. |
| `failed`: sem memória no `next build` | Suba `resources.memory_mb` do serviço. |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="app-next-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"node\"},
    \"port\": 3000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [Front Next com back Go privado e Postgres](/conectados/front-back-db/).
- [Galerias e imagens na CDN](/cdn/galerias/) para servir mídia com `next/image`.
- [Domínio próprio](/dominios/dominio-proprio/).

---

URL: https://docs.nebularws.com/guia/go.md

# Go

Um serviço Go vira um binário estático e roda numa imagem mínima (distroless) como usuário não-root. Sem Dockerfile.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

Com `builder: "auto"` (ou `"go"`), a Nebular procura `go.mod` na raiz do serviço (`root_dir`). Se houver um `Dockerfile`, **ele vence** os demais sinais: para forçar o buildpack Go, declare `build.builder: "go"`.

- Versão do Go: linha `toolchain` do `go.mod`, senão a linha `go`.
- Pacote a compilar: `.` se a raiz tem `package main`; senão o único `./cmd/<x>`. Com vários programas em `cmd/`, veja [Vários programas em `cmd/`](#vários-programas-em-cmd).
- Build: `go build -trimpath -ldflags="-s -w"` com `CGO_ENABLED=0` (binário estático). Sem checkout `.git`: `-buildvcs=false`.
- Start padrão: `/app/app` (o binário). Porta padrão do buildpack: 8080; declare `port` no serviço.
- Dependências C (cgo) exigem a variante glibc; se precisar, use [Dockerfile](/guia/dockerfile/).

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```go
// main.go: lê PORT, escuta em 0.0.0.0 e expõe /healthz
package main

import (
	"log"
	"net/http"
	"os"
)

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) { w.Write([]byte("ok")) })
	mux.HandleFunc("GET /", func(w http.ResponseWriter, _ *http.Request) { w.Write([]byte("olá da Nebular")) })
	log.Fatal(http.ListenAndServe("0.0.0.0:"+port, mux))
}
```

## Vários programas em `cmd/`

A Nebular escolhe o programa a publicar nesta ordem, e para na primeira regra que decide:

1. Há `package main` na raiz do módulo: publica a raiz (`.`).
2. Há um único `cmd/<x>` com `package main`: publica ele.
3. Há vários: escolhe o que tem o mesmo nome do final do módulo (linha `module` do `go.mod`).
4. Nenhum bate com o módulo: escolhe pela convenção de serviço web, na prioridade `server`, `app`, `api`, `web`, `gateway`, `http`, `service`, `main`, `cmd` (maiúsculas não importam). Vale o de maior prioridade presente.
5. Ainda sem decisão: o deploy falha com uma mensagem pedindo o **comando de build** do serviço.

Quando a escolha vem da convenção, o motivo aparece no log do deploy. Se não é o programa que você quer, force-o: o `build_command` do serviço **sempre** vence a detecção. O binário precisa sair em `/app/app`, que é o que o runtime executa.

```bash
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"build_command": "go build -o /app/app ./cmd/server"}'
```

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="api-go-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "api-go-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `go`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="api-go-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"go\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 8080}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="api-go-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"go\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/APP_ENV" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "producao"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `node_modules`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-go-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"go\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `failed`: "nenhum package main" | Ponha `package main` na raiz ou em `cmd/<x>`, ou defina `build_command`. |
| `failed`: vários programas em `cmd/` sem escolha possível | Defina `build_command` do serviço, por exemplo `go build -o /app/app ./cmd/server` (veja [Vários programas em `cmd/`](#vários-programas-em-cmd)). |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-go-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"go\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [Serviço privado e rede do grupo](/conectados/rede-privada/) para um back Go que só o front alcança.
- [PostgreSQL](/bancos/postgres/) para ligar `DATABASE_URL` ao serviço.
- [Front Next com back Go e Postgres](/conectados/front-back-db/).

---

URL: https://docs.nebularws.com/guia/rust.md

# Rust

Um serviço Rust é compilado com `cargo build --release --locked` e roda numa imagem mínima (distroless com libc) como não-root.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

Com `builder: "auto"` (ou `"rust"`) a Nebular procura `Cargo.toml` (um `Dockerfile`, se existir, vence).

- `Cargo.lock` é obrigatório no repositório (`--locked`).
- Binário: o `[[bin]]` com o nome do pacote; se houver um só `[[bin]]`, ele; senão o nome do pacote. Vários `[[bin]]` sem nenhum igual ao pacote, ou *workspace* virtual (sem `[package]`), exigem `build_command` e `start_command`.
- Versão do toolchain: `rust-version` do `Cargo.toml`; mais nova que a tabela da plataforma é erro.
- Runtime: distroless com libc, sem OpenSSL. Use `rustls` ou, se precisar de OpenSSL/bibliotecas do sistema, [Dockerfile](/guia/dockerfile/).
- Start padrão: `/app/app`. Porta padrão do buildpack: 8080; declare `port` no serviço.

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```rust
// src/main.rs (axum 0.8): lê PORT, escuta em 0.0.0.0, expõe /healthz
use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let port = std::env::var("PORT").unwrap_or_else(|_| "8080".into());
    let app = Router::new()
        .route("/healthz", get(|| async { "ok" }))
        .route("/", get(|| async { "olá da Nebular" }));
    let listener = tokio::net::TcpListener::bind(format!("0.0.0.0:{port}")).await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="api-rust-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "api-rust-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `rust`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="api-rust-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"rust\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 8080}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="api-rust-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"rust\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/RUST_LOG" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "info"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `target/` nem `node_modules`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-rust-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"rust\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `failed`: Cargo.lock / `--locked` | Versione o `Cargo.lock` (rode `cargo generate-lockfile` e inclua no envio). |
| `failed`: falta de memória (processo morto) | Compilação Rust é pesada: suba `resources.memory_mb` do serviço (`PATCH` no serviço) ou use Dockerfile com cache. |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-rust-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"rust\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [Rede privada](/conectados/rede-privada/) para expor o serviço só ao grupo.
- [Dockerfile](/guia/dockerfile/) quando precisar de bibliotecas do sistema.

---

URL: https://docs.nebularws.com/guia/python.md

# Python (FastAPI)

Um serviço Python instala as dependências com `pip` e roda como não-root numa imagem `python` slim. Este guia usa FastAPI; Flask e Django também são detectados.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

Com `builder: "auto"` (ou `"python"`) a Nebular procura `pyproject.toml`, `requirements.txt` ou `Pipfile` (um `Dockerfile`, se existir, vence).

- FastAPI/Starlette/uvicorn: start `python -m uvicorn <modulo>:app --host 0.0.0.0 --port 8000`, onde o módulo é achado em `main.py`, `app.py`, `server.py`, `app/main.py` ou `src/main.py` (o arquivo precisa conter `FastAPI(`). Não achou: defina `start_command`.
- Flask: `gunicorn <modulo>:app`; Django: `gunicorn <pacote>.wsgi:application` (exige `manage.py`). Sem framework web: `python main.py` ou `python app.py`.
- Dependências: `requirements.txt` (`pip install -r`), `Pipfile` ou `pyproject.toml` (`pip install .`), instaladas em `/app/deps` (`PYTHONPATH` já ajustado). Pacotes nativos que precisem de compilador **não** funcionam na imagem slim: use [Dockerfile](/guia/dockerfile/).
- Porta padrão do buildpack: 8000; declare `port` no serviço (use o mesmo valor em `PORT`).

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```python
# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/healthz")
def healthz():
    return {"ok": True}

@app.get("/")
def raiz():
    return {"msg": "olá da Nebular"}
```

```text
# requirements.txt
fastapi
uvicorn
```

Fixe versões em `requirements.txt` para builds reproduzíveis. O start padrão escuta na porta 8000; para outra porta, defina `start_command` com `--port` e `port` igual.

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="api-py-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "api-py-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `python`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="api-py-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"python\"},
    \"port\": 8000,
    \"healthcheck_path\": \"/healthz\"
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 8000}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="api-py-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"python\"},
    \"port\": 8000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/LOG_LEVEL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "info"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `.venv`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-py-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"python\"},
    \"port\": 8000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `failed`: "app (FastAPI/Flask) não encontrado" / "comando de start desconhecido" | Defina `start_command` (por exemplo `python -m uvicorn pacote.app:app --host 0.0.0.0 --port 8000`). |
| `failed` ao instalar uma dependência | A imagem não tem compilador: use uma roda binária (wheel) ou [Dockerfile](/guia/dockerfile/). |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="api-py-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"python\"},
    \"port\": 8000,
    \"healthcheck_path\": \"/healthz\"
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [PostgreSQL](/bancos/postgres/) e [migrações](/bancos/migracoes/).
- [Variáveis e referências](/conectados/variaveis-e-referencias/).

---

URL: https://docs.nebularws.com/guia/site-estatico.md

# Site estático

Um site estático não tem container de execução: a borda serve os arquivos. Pode ter um passo de build (Vite, Astro, Hugo via `package.json`) ou ser HTML puro.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

Com `builder: "auto"` (ou `"static"`) a Nebular decide assim (um `Dockerfile`, se existir, vence):

- Sem `package.json`, com `index.html` na raiz: publica os arquivos como estão.
- `package.json` **sem** `scripts.start`: instala (`npm ci`/`npm install`) e roda `npm run build` (ou o `build_command`).
- A pasta publicada é a primeira, nesta ordem, que contenha `index.html`: `dist`, `out`, `build`, `public`, a raiz. Nenhum `index.html` encontrado é erro.
- Não há processo para consultar variáveis em runtime: valores só entram **em tempo de build**. Por isso, nunca ponha segredo em variável de site estático: ela vai parar no bundle do browser.
- `port` e `healthcheck_path` não se aplicam ao estático.

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```json
{
  "scripts": { "build": "vite build" }
}
```

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="site-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "site-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `static`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="site-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"static\"},
    \"port\": 3000
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 3000}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="site-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"static\"},
    \"port\": 3000
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/VITE_API_URL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "https://api.exemplo.com"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `node_modules`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="site-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"static\"},
    \"port\": 3000
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `failed`: "nenhum index.html encontrado" | Gere o `index.html` em `dist`, `out`, `build`, `public` ou na raiz (confira o `build_command`). |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="site-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"static\"},
    \"port\": 3000
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [Domínio próprio](/dominios/dominio-proprio/) e [TLS](/dominios/tls/).
- [Node.js e Next.js](/guia/nodejs-next/) para renderização no servidor.

---

URL: https://docs.nebularws.com/guia/dockerfile.md

# Dockerfile

Quando as stacks automáticas não servem (bibliotecas do sistema, cgo, compilador Python), escreva um `Dockerfile`. A Nebular o constrói com BuildKit rootless isolado e roda a imagem resultante endurecida.

## Pré-requisitos

- Token com os escopos `projects:write`, `deploy`, `env:write` e `logs:read` (veja [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/)). Para listar projetos e serviços, `projects:read`.
- `NEBULAR_API` e `NEBULAR_TOKEN` no ambiente; `curl` e `jq` instalados.
- Toda chamada que cria algo leva `Idempotency-Key`: repetir após timeout é seguro.

## Como a Nebular constrói este tipo de app

- Um `Dockerfile` na raiz (`root_dir`) **vence** a detecção automática. Para apontar outro arquivo: `build: {"builder": "dockerfile", "dockerfile_path": "docker/Dockerfile.prod"}` (relativo ao `root_dir`; não pode sair dele).
- O contexto do build é o `root_dir` do serviço. O build roda sem acesso à rede interna e com tempo limite (10 min por padrão).
- Só `linux/arm64` (os servidores são ARM): não use `FROM --platform=` com outra plataforma. Imagens-base multi-arch funcionam.
- Variáveis de build: só entram como `--build-arg` as variáveis do próprio serviço cujo nome o `Dockerfile` declara com `ARG`.
- Limites da imagem resultante: tamanho total e número de camadas (127). Imagem acima do limite é recusada.
- **Usuário não-root:** declare `USER` com um uid sem privilégio. Se o `USER` for vazio ou root, a plataforma força um uid não-root; se o app não funcionar assim, o deploy termina em `failed`.
- Runtime: sistema de arquivos somente leitura, `/tmp` em tmpfs, sem capabilities. Escreva só em `/tmp` ou num [volume](/conectados/volumes/).
- `EXPOSE` é informativo: o que vale é o `port` do serviço, e o app precisa escutar `0.0.0.0:$PORT`.

Regras comuns a todas as stacks:

- O app precisa escutar em `0.0.0.0` na porta que o serviço declara em `port` e que a plataforma também entrega na variável `PORT`. Leia `PORT` do ambiente; declare `port` no serviço com o mesmo valor.
- O container roda sem root, com sistema de arquivos somente leitura e `/tmp` em tmpfs (64 MB). Não grave em outro lugar; para dados persistentes use um [volume](/conectados/volumes/) ou um [banco](/bancos/postgres/).
- Segredo vai em variável do serviço (`env:write`), nunca no código, nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

```dockerfile
# Dockerfile multi-stage para um serviço Go (exemplo)
FROM golang:1.25 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/api

FROM gcr.io/distroless/static-debian12
COPY --from=build /out/app /app
USER 65532:65532
EXPOSE 8080
ENTRYPOINT ["/app"]
```

## 1. Criar o projeto

O projeto é o grupo: todos os seus serviços compartilham uma rede privada. Guarde o `id` da resposta.

```bash
NAME="app-df-$(date +%s)-$RANDOM"
curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}"
```
```json
{"id": "01j9zkk07fhzv5zsmn996cdwpb", "name": "app-df-1760000000"}
```

| Resposta | O que fazer |
|---|---|
| `401` | Token ausente ou inválido: confira o cabeçalho; peça outro token a uma pessoa. |
| `403` | Falta `projects:write`: peça um token com o escopo. |
| `409 slug_taken` / `project_quota_exceeded` | Já existe projeto com esse slug (derivado do nome): escolha outro nome (ou repita com a mesma `Idempotency-Key` para recuperar a resposta anterior); ou o time atingiu o limite de projetos. |
| `429` | Espere `Retry-After` segundos e repita. |

## 2. Criar o serviço

O serviço `web` é público (`visibility: "public"` exige um `slug` único) e usa fonte `upload` e o builder `dockerfile`. Este bloco é autossuficiente: cria o projeto e o serviço.

```bash
NAME="app-df-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"dockerfile\", \"dockerfile_path\": \"Dockerfile\"},
    \"port\": 3000
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 3000}
```

Campos úteis do serviço: `healthcheck_path` (caminho HTTP que deve responder 2xx), `start_command` e `build_command` (substituem o padrão), `resources` (`{"memory_mb": 512, "cpus": 0.5}`, valores padrão; sempre dentro de `resources`) e `auto_deploy`.

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Corpo inválido: o `name` do serviço segue `^[a-z][a-z0-9-]{0,30}$`; `build.builder` deve ser um de `auto`, `node`, `go`, `rust`, `python`, `static`, `dockerfile`. |
| `404` | Projeto inexistente **ou** de outro time (a API não diferencia). Confira o `id`. |
| `409 name_taken` / `slug_taken` | Já existe serviço com esse nome no projeto (todo projeto nasce com um `web`), ou o `slug` está em uso. |

## 3. Variáveis

Defina as variáveis antes do deploy: elas são resolvidas na hora do deploy. O valor pode referenciar outros serviços (`${{db.DATABASE_URL}}`) ou o grupo (`${{shared.VAR}}`); veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

```bash
NAME="app-df-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"dockerfile\", \"dockerfile_path\": \"Dockerfile\"},
    \"port\": 3000
  }" | jq -r .id)

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/APP_ENV" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "producao"}'
```
Resposta: `200`. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares vão para o bundle do browser: nunca ponha segredo nelas.

| Resposta | O que fazer |
|---|---|
| `403` | Falta `env:write`. |
| `400 invalid_request` | Nome de variável inválido ou valor acima de 64 KiB. |
| `unresolved_reference` / `reference_cycle` | Aparecem no **deploy**, não aqui (o `PUT` aceita a referência): o `POST` do deploy responde `422` e nada é criado; `details.references` lista os nomes com problema (uma `${{...}}` aponta para variável inexistente ou forma ciclo). Corrija a variável citada. |

## 4. Enviar o código, fazer o deploy e esperar

Compacte a pasta do projeto (sem `node_modules`, `.git` nem arquivos `.env`) e envie como `multipart/form-data` para o serviço. A fonte `upload` não usa git: cada envio é um deploy. Se o serviço tem fonte `git` (`{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main"}`) ou `image`, o `POST` de deploy usa a fonte configurada no serviço.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="app-df-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"dockerfile\", \"dockerfile_path\": \"Dockerfile\"},
    \"port\": 3000
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"

# código: a pasta do projeto, sem node_modules, .git nem .env
ARQ=$(mktemp)
tar --exclude=node_modules --exclude=.git --exclude='.env*' -czf "$ARQ" .
RESP=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" \
  -H "Idempotency-Key: deploy-$(sha256sum "$ARQ" | cut -c1-16)-$RANDOM" \
  -F "file=@$ARQ")
D=$(echo "$RESP" | jq -r .id)     # resposta: 202 {"id": "dep_...", "status": "queued"}

# polling com backoff: 2 s, dobrando até 30 s, no máximo 40 tentativas (~10 min)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública do serviço vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | tee /dev/stderr | jq -e '.public_url | startswith("https://")' >/dev/null
```

Com o deploy `ready`, chame `<public_url>/healthz` (esperado `200`; exige DNS e o container no ar, por isso esse último passo não roda no teste).

Estados do deploy: `queued`, `building`, `deploying`, `ready` (sucesso), e os finais de falha `failed`, `blocked` (um serviço do qual este depende falhou), `canceled`, `superseded` (um deploy mais novo o substituiu). Não há webhooks: faça polling. Detalhes em [Deploys e status](/operacao/deploys-e-status/).

| Estado ou resposta | O que fazer |
|---|---|
| `failed` | Leia o log de build (passo 5). Corrija o código ou a configuração e faça um novo deploy. Não repita igual. |
| `422 unresolved_reference` ao disparar o deploy | Variável referenciada não existe: crie-a ou corrija o nome (`details.references` diz qual). |
| `422 reference_cycle` ao disparar o deploy | Duas variáveis se referenciam: quebre o ciclo. |
| `blocked` | Corrija primeiro o serviço do qual este depende. |
| `404` | O deploy ou serviço não existe ou não é seu. |
| `401` / `403` | Token inválido / sem escopo `deploy`. Pare e peça outro token. |
| `429` | Espere `Retry-After` e repita o `GET` (o polling já faz backoff). |
| `503` | Transitório: repita com backoff. |
| `quota_exceeded` | Limite de serviços, memória ou volume do plano: veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `failed`: plataforma não suportada | O `Dockerfile` pede outra plataforma que não `linux/arm64`: remova o `--platform`. |
| `failed`: build-arg não permitido | O `--build-arg` não é uma variável do serviço: crie a variável antes. |
| `failed`: build morto (provável falta de memória) ou tempo limite | Reduza o build (cache de camadas, menos paralelismo). |
| `failed` com permissão negada ao iniciar | O app só funciona como root: ajuste permissões (`chown`) e use `USER` não-root. Root não é permitido. |

## 5. Logs e rollback

Log do build (deploys `failed`) e log de execução, ambos com paginação por `cursor`; precisam do escopo `logs:read`.

```bash
# preparo (passos 1 e 2): projeto e serviço, para o bloco rodar sozinho
NAME="app-df-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"$NAME\",
    \"source\": {\"type\": \"upload\"},
    \"build\": {\"builder\": \"dockerfile\", \"dockerfile_path\": \"Dockerfile\"},
    \"port\": 3000
  }" | jq -r .id)
H="Authorization: Bearer $NEBULAR_TOKEN"
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# log do build do deploy D
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" -H "$H"

# log de execução do serviço
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/logs" -H "$H"

# rollback: volta ao deployment anterior do serviço, com as variáveis resolvidas daquela versão
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: rollback-$D" -d '{}'
```

O rollback cria um novo deploy; faça o polling dele como no passo 4. Veja [Rollback](/operacao/rollback/) e [Logs](/operacao/logs/).

## Veja também

- [Imagem pública](/guia/imagem-publica/) para usar uma imagem pronta sem build.
- [Volumes](/conectados/volumes/) para dados persistentes.

---

URL: https://docs.nebularws.com/guia/imagem-publica.md

# Imagem pública

Use uma imagem pronta quando o software já é distribuído assim (Nginx, Ghost, Metabase). Não há build: a Nebular resolve a imagem, confere e roda.

## Pré-requisitos

- Token com `projects:write`, `deploy`, `env:write` e `logs:read` ([Token de API](/comecar/token/)).
- A imagem precisa estar num registry da lista permitida (padrão: `docker.io`, `ghcr.io`, `quay.io`), ser **pública** (sem login) e ter manifesto `linux/arm64` (os servidores são ARM).

## O que a plataforma faz com a imagem

1. Resolve a tag para um **digest** `sha256:` (se `source.ref` já traz `@sha256:...`, esse digest fixa a versão) e baixa a imagem verificando o hash. A plataforma escolhe a variante `linux/arm64` do manifesto; imagem só `amd64` é recusada. Tamanho total e número de camadas têm limite; acima disso a imagem é recusada.
2. Roda **sem root**: se o `USER` da imagem for vazio ou root, a plataforma força um uid sem privilégio (`65534`). Se o app não funcionar assim, o container encerra e o deploy termina em `failed` com `error.code = image_requires_root` (a mensagem pede `build.user`). Não há como rodar como root: declare `build.user` (`uid[:gid]`) com um usuário que a imagem suporte, ou escolha uma variante *unprivileged*.
3. Sistema de arquivos **somente leitura**, `/tmp` em tmpfs de 64 MB, sem capabilities, `no-new-privileges`. Dados persistentes só num [volume](/conectados/volumes/).
4. Como não é root, o app **não pode escutar portas abaixo de 1024**. Use uma imagem que escute em 8080 (ou configure a porta por variável) e declare `port` igual.

Fixe sempre por digest em produção: veja [Fixar por digest e como obter o digest](#fixar-por-digest-e-como-obter-o-digest).

## Fixar por digest e como obter o digest

A forma aceita pela API é **`source.ref = "repo[:tag]@sha256:<64 hex>"`**: o digest vai **dentro** do `ref`, depois de um `@` (o `:tag` é opcional e só serve de legenda para humanos; quem manda é o digest). Exemplo: `docker.io/nginxinc/nginx-unprivileged:1.27-alpine@sha256:0123...cdef`. O mesmo formato vale no corpo do deploy, `{"image": "repo:tag@sha256:..."}`, que atualiza a imagem do serviço e implanta (corpo sem `@sha256:` é recusado com `400 invalid_request`). Não há campo `digest` separado no contrato. Com só a tag no `ref`, a plataforma resolve a tag no momento do deploy e registra o digest escolhido em `image_digest` do deployment.

Como obter o digest de uma tag (rode na sua máquina ou no CI, não é uma rota da Nebular):

```bash
# mostra o digest do índice (linha "Digest:") e as plataformas disponíveis
docker buildx imagetools inspect docker.io/nginxinc/nginx-unprivileged:1.27-alpine

# só o digest (índice multi-arch)
crane digest docker.io/nginxinc/nginx-unprivileged:1.27-alpine

# digest da variante arm64 isolada
crane digest --platform linux/arm64 docker.io/nginxinc/nginx-unprivileged:1.27-alpine
```

**Arquitetura:** os servidores de produção são `linux/arm64`. Confira na saída do `imagetools inspect` que existe uma entrada `Platform: linux/arm64`. O digest do **índice** (multi-arch) serve: a plataforma escolhe nele a variante arm64. O digest de uma variante isolada só serve se ela for `linux/arm64`; o digest de uma variante `amd64` falha o deploy com "a imagem não tem variante linux/arm64". Imagem que você mesmo constrói: publique multi-arch ou só arm64 (`docker buildx build --platform linux/arm64 --push ...`).

```bash
# DIGEST de exemplo (64 hex): no uso real, o digest obtido acima
DIGEST=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
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\": \"digest-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"port\": 8080, \"source\": {\"type\": \"image\", \"ref\": \"docker.io/nginxinc/nginx-unprivileged:1.27-alpine@$DIGEST\"}}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -H "Idempotency-Key: digest-$SUF" \
  -d "{\"image\": \"docker.io/nginxinc/nginx-unprivileged:1.27-alpine@$DIGEST\"}"
```
```json
{"id": "01j9zkv1t9ndd76xmr8ahxee7p", "service_id": "01j9zk32py7tcbz2q0ra5aqx7k", "status": "queued", "trigger": "api", "source_ref": "docker.io/nginxinc/nginx-unprivileged:1.27-alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "image_digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}
```

## 1. Criar o serviço com `source.type = image`

```bash
NAME="vitrine-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | jq -r .id)

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\": \"$NAME\",
    \"source\": {\"type\": \"image\", \"ref\": \"docker.io/nginxinc/nginx-unprivileged:1.27-alpine\"},
    \"port\": 8080,
    \"healthcheck_path\": \"/\"
  }"
```
```json
{"id": "01j9zk32py7tcbz2q0ra5aqx7k", "name": "web", "kind": "app", "visibility": "public", "port": 8080}
```

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | `source.type` deve ser `upload`, `git` ou `image`; confira `ref` (formato `registro/org/imagem:tag`, ou `registro/org/imagem:tag@sha256:<digest>`). |
| `404` | Projeto inexistente ou de outro time (indistinguíveis). |
| `409 name_taken` / `slug_taken` | Nome de serviço ou `slug` já em uso. |
| `403` | Falta `projects:write`. |

## 2. Deploy e polling

Para fonte `image`, o `POST` de deploy usa a fonte configurada no serviço (sem corpo).

```bash
# preparo (passo 1): projeto e serviço de imagem
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\": \"vitrine-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)

# fonte image: o POST de deploy usa a imagem configurada no serviço (corpo {})
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -H "Idempotency-Key: deploy-nginx-$SUF" -d '{}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]
```

| Estado ou erro | O que fazer |
|---|---|
| `failed` com `error.code = image_requires_root` | A imagem só funciona como root. Declare `build.user` (`uid[:gid]`, nunca root) no serviço, ou troque por uma variante sem privilégio (`-unprivileged`, `-rootless`, distroless) ou use [Dockerfile](/guia/dockerfile/) para ajustar permissões. |
| `failed`: registry fora da lista permitida | Use `docker.io`, `ghcr.io` ou `quay.io` (ou peça ao operador para incluir o registry). |
| `failed`: "a imagem não tem variante linux/arm64" | Escolha outra tag ou uma imagem multi-arch com `linux/arm64`; um digest `amd64` não serve. |
| `failed`: imagem maior que o limite / camadas demais | Use uma variante menor (alpine, slim). |
| `failed`: digest não confere / imagem não encontrada pelo digest | O digest no `ref` não existe no registry ou não bate com o conteúdo; obtenha-o de novo (veja acima). |
| `failed` com o app caindo logo após subir | Leia o log de execução (`GET .../services/$S/logs`): porta errada, escrita em disco somente leitura (mova para `/tmp` ou volume). |
| `503` | Transitório: repita com backoff. |

Veja também [Deploys e status](/operacao/deploys-e-status/), [Logs](/operacao/logs/) e [Rollback](/operacao/rollback/).

## 3. Variáveis e atualização

Configure a imagem por variáveis ([Variáveis e referências](/conectados/variaveis-e-referencias/)). Para atualizar a versão, mude `source.ref` (nova tag e novo `@sha256:...`) com `PATCH` no serviço e faça um novo deploy; o rollback volta ao deployment anterior.

```bash
NAME="vitrine-$(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: $NAME-projeto" \
  -d "{\"name\": \"$NAME\"}" | 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\": \"private\", \"source\": {\"type\": \"image\", \"ref\": \"docker.io/nginxinc/nginx-unprivileged:1.27-alpine\"}, \"port\": 8080}" | jq -r .id)

curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/$S" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "docker.io/nginxinc/nginx-unprivileged:1.27.5-alpine"}}'
```

---

URL: https://docs.nebularws.com/guia/wordpress.md

# WordPress

O template `wordpress` instancia, de uma vez, um banco MariaDB gerenciado e o serviço WordPress ligado a ele. Você não escreve Dockerfile nem variáveis de banco.

## Pré-requisitos

- Token com `projects:write`, `templates:deploy`, `deploy` e `logs:read` ([Tokens e escopos](/seguranca/tokens-e-escopos/)).
- Mínimo de **512 MB e 1 vCPU** para o serviço (recomendado 2 vCPU para tráfego real). Confira o que o seu plano permite em `GET /v1/limits`.

## O que o template configura

Serviços criados (nomes fixos):

| Serviço | Tipo | Detalhes |
|---|---|---|
| `db` | `database`, motor `mariadb` | cota de 1024 MB |
| `web` | `app`, público | imagem `wordpress:6.9.4-php8.3-apache` fixada por digest, porta 8080, volume `wp-content` de 5 GB em `/var/www/html/wp-content` |

O `web` que todo projeto novo já traz **não precisa ser apagado**: se ainda estiver virgem (sem deploy, variáveis, domínio ou volume), o template o **adota** (o `id` do serviço é o mesmo) e o configura. Se o `web` já foi usado, a instanciação responde `409 name_taken` e nada é criado.

Como o WordPress roda na plataforma:

- Roda como `33:33` (`www-data`), sistema de arquivos **somente leitura**; tmpfs em `/var/www/html` (128 MB), `/tmp`, `/var/run/apache2` e `/var/lock/apache2`. Só `wp-content` (o volume) persiste: plugins, temas e uploads ficam lá.
- As variáveis de banco vêm por referência (`WORDPRESS_DB_HOST=${{db.MYSQL_HOST}}:${{db.MYSQL_PORT}}`, `..._USER`, `..._PASSWORD`, `..._NAME`); a conexão usa TLS com verificação do certificado do servidor.
- As chaves e *salts* (`WORDPRESS_AUTH_KEY` etc.) são geradas por instância com `{{generate:secret64}}` (CSPRNG) e gravadas como variáveis **sensíveis**.
- O `wp-cron` do WordPress é desligado (`DISABLE_WP_CRON`) e a plataforma faz um `GET /wp-cron.php?doing_wp_cron` interno a cada 5 minutos pela rede do grupo (sem shell, sem comando arbitrário).
- O proxy responde `404` para `/xmlrpc.php`, `/readme.html` e `/license.txt` antes de chegar ao app.
- Atualizações automáticas do WordPress ficam desligadas (`AUTOMATIC_UPDATER_DISABLED`): **atualizar é trocar a imagem do template** (veja abaixo).

## 1. Ver o template e seus parâmetros

```bash
curl -sS "$NEBULAR_API/v1/templates" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"items": [{"id": "wordpress", "name": "WordPress", "version": 1}], "next_cursor": null, "has_more": false}
```

Cada item traz `params` (nome, tipo e padrão). O template declara o parâmetro `table_prefix` (texto, padrão `"wp_"`): o prefixo das tabelas do WordPress, até 16 caracteres, no formato `^[a-z][a-z0-9_]{0,14}_$`.

| Resposta | O que fazer |
|---|---|
| `401` / `403` | Token inválido ou sem escopo: pare e peça outro. |
| `429` | Espere `Retry-After`. |

## 2. Instanciar

Crie o projeto e instancie o template nele. A instanciação é **atômica** (se qualquer parte falhar, tudo que foi criado é desfeito) e **idempotente** pela `Idempotency-Key`: repetir a mesma chamada depois de timeout devolve o mesmo resultado e não duplica serviços.

```bash
NAME="blog-$(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\": \"$NAME\"}" | jq -r .id)

# o `web` que o projeto já traz, se virgem, é adotado pelo template (não apague)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/templates/wordpress" \
  -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-wordpress" \
  -d '{"params": {"table_prefix": "wp_"}}'
```
```json
{"template_id": "wordpress", "version": 1, "project_id": "01j9zkk07fhzv5zsmn996cdwpb", "services": [{"id": "01j9zkff8y1dmcwa49fanx9qak", "name": "db", "kind": "database"}, {"id": "01j9zkwf4q15w38y0taf680jvv", "name": "web", "kind": "app"}], "deploy_started": true}
```

| Resposta | O que fazer |
|---|---|
| `404` | Projeto ou template inexistente (ou projeto de outro time). |
| `400 invalid_request` | `params` inválido (tipo ou parâmetro desconhecido). |
| `409 name_taken` | O projeto já tem um serviço `db`, ou o `web` já foi usado (tem deploy, variáveis, domínio ou volume). Use um projeto novo, ou limpe o `web`. Um `web` virgem **não** dá erro: é adotado. |
| `422 quota_exceeded` | Limite do plano (serviços, memória, volume ou cota de banco). Veja [Limites e cotas](/operacao/limites-e-cotas/). |
| `503 unavailable` | O nó de banco está indisponível: nada foi criado (atômico); repita a **mesma** chamada com backoff de 5, 10, 20, 40 s. |

## 3. Acompanhar os deploys

Liste os serviços do projeto, pegue o deployment mais novo do `web` e faça polling dele por id. O `web` só fica `ready` depois que o banco `db` está provisionado (ele depende do `db` pelas referências); se o `db` falhar, o `web` termina `blocked`.

```bash
NAME="blog-$(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\": \"$NAME\"}" | jq -r .id)

# o `web` que o projeto já traz, se virgem, é adotado pelo template (não apague)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/templates/wordpress" \
  -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-wordpress" \
  -d '{"params": {"table_prefix": "wp_"}}' >/dev/null

S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[] | select(.name=="web") | .id')

# o deploy do template é o mais novo da lista; acompanhe-o pelo id
D=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" | jq -r '.items[0].id')

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r '.status')
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

# a URL pública vem em public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" | jq -e '.public_url | startswith("https://")'  >/dev/null
```

Para ver o `409` quando o `web` já foi usado:

```bash
NAME="blog-$(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\": \"$NAME\"}" | jq -r .id)

# usa o web (variável) e então tenta o template
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/web/variables/FOO" -H "$H" -H "Content-Type: application/json" \
  -d '{"value": "bar"}' >/dev/null

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/templates/wordpress" \
  -H "$H" -H "Content-Type: application/json" -d '{"params": {}}'
```

Abra `$URL/wp-admin/install.php` no navegador (ou complete a instalação do WordPress por uma pessoa): criar o usuário administrador é um passo humano.

| Estado ou erro | O que fazer |
|---|---|
| `blocked` no `web` | O `db` falhou: leia os logs de build/provisionamento do `db` e corrija. |
| `422 unresolved_reference` ao disparar o deploy | Uma variável `${{db.…}}` não existe: o serviço `db` foi apagado ou renomeado. |
| 502 / health check falhando | Memória insuficiente (suba `resources.memory_mb` para 512 ou mais, `resources.cpus` para 1) ou banco ainda em `provisioning`. Leia os logs de execução do `web`. |
| `503 unavailable` | Banco indisponível: repita com backoff; não recrie. |

## Domínio, backups e atualização

- URL gerada: [Subdomínio gerado](/dominios/subdominio-gerado/); domínio próprio: [Domínio próprio](/dominios/dominio-proprio/).
- O banco tem backup diário (7 diários e 4 semanais) e sob demanda: [Backup e restore](/bancos/backup-restore/). `wp-content` (volume) é separado: veja [Volumes](/conectados/volumes/).
- **Atualizar o WordPress** = trocar `source.ref` (nova tag e novo `@sha256:...`) do serviço `web` por uma versão mais nova da imagem oficial e fazer um novo deploy; o rollback volta à versão anterior. Faça backup do banco antes.

```bash
NAME="blog-$(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\": \"$NAME\"}" | jq -r .id)

# o `web` que o projeto já traz, se virgem, é adotado pelo template (não apague)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/templates/wordpress" \
  -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NAME-wordpress" \
  -d '{"params": {"table_prefix": "wp_"}}' >/dev/null
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[] | select(.name=="web") | .id')

curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/$S" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "wordpress:6.9.5-php8.3-apache"}}'
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
  -H "$H" -H "Content-Type: application/json" -H "Idempotency-Key: wp-update-$NAME" -d '{}'
```

---

URL: https://docs.nebularws.com/guia/monorepo.md

# Monorepo

Um repositório com `apps/web` e `apps/api` vira **dois serviços do mesmo projeto**, cada um com seu `root_dir`. O projeto é o grupo: os serviços se enxergam pela [rede privada](/conectados/rede-privada/).

## Pré-requisitos

- Token com `projects:write`, `deploy` e `env:write`.
- Integração GitHub instalada no time (o `installation_id` identifica a instalação). A rota para listar instalações não faz parte do contrato v13: pegue o `installation_id` no painel.

## Fonte git por serviço

A fonte do serviço é `{"type": "git", "installation_id": "...", "repo": "org/repo", "branch": "main", "root_dir": "/apps/api", "watch_paths": ["apps/api/**"]}`.

- `root_dir`: subdiretório do repositório que é a raiz do serviço (detecção da stack, Dockerfile e contexto de build partem dele). Não pode sair do repositório.
- `watch_paths`: padrões que decidem se um push afeta o serviço. Sem `watch_paths`, todo push na branch o afeta.
- Cada serviço escolhe seu `build.builder` (`auto` detecta pela raiz do serviço).

```bash
# INSTALL: installation_id da integração GitHub do time
NAME="mono-$(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: $NAME-projeto" -d "{\"name\": \"$NAME\"}" | jq -r .id)

# API privada (só o front alcança), em Go
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"api\", \"kind\": \"app\", \"visibility\": \"private\", \"port\": 8080, \"auto_deploy\": true,
       \"build\": {\"builder\": \"go\"},
       \"source\": {\"type\": \"git\", \"installation_id\": \"$INSTALL\", \"repo\": \"org/repo\", \"branch\": \"main\",
                    \"root_dir\": \"/apps/api\", \"watch_paths\": [\"apps/api/**\"]}}"

# front público, em Next.js
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\": \"$NAME\", \"port\": 3000, \"auto_deploy\": true,
       \"build\": {\"builder\": \"node\"},
       \"source\": {\"type\": \"git\", \"installation_id\": \"$INSTALL\", \"repo\": \"org/repo\", \"branch\": \"main\",
                    \"root_dir\": \"/apps/web\", \"watch_paths\": [\"apps/web/**\", \"packages/ui/**\"]}}"
```

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | `root_dir` inválido ou `source.type` desconhecido. |
| `404` | Projeto inexistente ou de outro time (indistinguíveis). |
| `409 name_taken` / `slug_taken` | Nome ou `slug` já em uso. |

## Auto-deploy por git

Com `auto_deploy: true`, o push na branch aciona o deploy. O webhook do GitHub encontra **todos** os serviços ligados ao repositório e à branch; com `watch_paths`, só os afetados pelos arquivos do push. Se mais de um serviço do grupo for afetado, o resultado é **um deploy de grupo**.

## Deploy de grupo

`POST /v1/projects/{p}/deploy` publica o grupo em **ordem topológica das referências**: o serviço referenciado sobe antes de quem o referencia (por exemplo `api` antes de `web`, se `web` usa `${{api.PRIVATE_URL}}`). Se o build de um serviço falhar, os dependentes ficam `blocked`; os que já estavam ativos continuam no ar.

```bash
G=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: grupo-mono-1" -d '{}' | jq -r .id)

# polling do GRUPO: um GET mostra o status geral e o de cada serviço
curl -sS "$NEBULAR_API/v1/projects/$P/group-deployments/$G" -H "Authorization: Bearer $NEBULAR_TOKEN" \
  | jq -r '.status, (.items[] | "\(.service_id) \(.status)")'
```

O corpo é `{}` com `Content-Type: application/json`; o `POST` também é aceito **sem corpo** (nesse caso o `Content-Type` é dispensável). O polling é feito no **grupo** (`GET /v1/projects/{p}/group-deployments/{g}`), não serviço a serviço. Repita a consulta com backoff (2 s, dobrando até 30 s, até ~10 min) até o `status` do grupo deixar de ser `running`: `ready` é sucesso; `failed`, `canceled` ou `superseded` são finais, e o item `failed` traz o `deployment_id` cujo log de build você lê (`GET .../deployments/{d}/logs`). Os itens têm `status` próprio (`queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `skipped`).

Exemplo executável (projeto de imagem; primeiro com `{}`, depois sem corpo):

```bash
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\": \"mono3-$SUF\"}" | jq -r .id)
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' >/dev/null

# 1) com Content-Type e {}: a forma que funciona em qualquer cliente
G=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mono3-a-$SUF" -d '{}' | jq -r .id)
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/group-deployments/$G" -H "$H" | jq -r .status)
  [ "$st" = running ] || break
  sleep 2
done
[ "$st" = ready ]

# 2) sem corpo e sem Content-Type: também aceito (vale {})
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" -H "$H" -H "Idempotency-Key: mono3-b-$SUF"
```

| Estado ou erro | O que fazer |
|---|---|
| `blocked` | Um serviço do qual este depende falhou: conserte-o primeiro e redeploye o grupo. |
| `422 unresolved_reference` ao disparar o deploy | Uma `${{serviço.VAR}}` aponta para variável ou serviço inexistente (a lista vem no erro). |
| `422 reference_cycle` ao disparar o deploy | Os serviços se referenciam em ciclo: quebre o ciclo. |
| `429` | Espere `Retry-After`. |

Rollback é **por serviço**: `POST .../services/{s}/deployments/{d}/rollback` ([Rollback](/operacao/rollback/)). Para variáveis e referências entre serviços, veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

---

URL: https://docs.nebularws.com/bancos/postgres.md

# PostgreSQL

Um banco gerenciado é um **serviço** `kind=database` do projeto. Ele vive no nó de banco (outro host), **não** na rede privada do grupo: os apps o acessam pela URL com TLS. Escopo do token: `databases:write` (criar, apagar, rotacionar) e `projects:read` (ler). Veja [Tokens e escopos](/seguranca/tokens-e-escopos/).

## 1. Criar

`name` é o nome do serviço (`^[a-z][a-z0-9-]{0,30}$`, único no projeto; é o prefixo das referências `${{db.…}}`). `engine` é `postgres`, `mariadb` ou `sqlite`; `quota_mb` é a cota em MB.

```bash
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-pg-$SUF\"}" | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pg-db-$SUF" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}'
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "postgres", "status": "provisioning", "quota_mb": 1024}
```

O banco nasce em `provisioning` e vira `ready`. Consulte `GET /v1/projects/$P/databases/{s}` com backoff (2 s, dobrando até 30 s, até uns 10 min) até o banco estar pronto antes de fazer deploy dos dependentes:

```bash
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-pg-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pg-db-$SUF" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  [ "$st" = ready ] && break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "postgres", "status": "ready", "quota_mb": 1024, "read_only": false}
```

## 2. Variáveis entregues

Todas **sensíveis** (mascaradas em log e UI) e referenciáveis por qualquer serviço do grupo:

| Variável | Conteúdo |
|---|---|
| `DATABASE_URL` | `postgres://<papel>:<senha>@<public_host>:5432/<db>?sslmode=verify-full` |
| `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` | as mesmas peças, separadas |

O certificado do `public_host` é de CA pública (Let's Encrypt): `sslmode=verify-full` funciona sem instalar CA própria. **Não** troque para `sslmode=disable`/`require`.

No app, use por referência (nunca copie o valor): `${{db.DATABASE_URL}}`. Veja [Conexão e referências](/bancos/conexao-e-referencias/).

Ler o valor em claro exige o escopo `env:reveal` num token criado com step-up (`GET …/variables?resolved=true`). Sem ele, o valor vem mascarado. As credenciais também saem de `POST /v1/projects/{p}/databases/{s}/credentials` (exige `env:reveal`): `{"credentials": [{"name": "DATABASE_URL", "value": "..."}, ...]}`.

## 3. Conectar de fora (diagnóstico)

Com as credenciais reveladas, use as variáveis padrão do libpq:

```bash
PGSSLMODE=verify-full psql "$DATABASE_URL" -c 'select 1'
```

## 4. Cota

`quota_mb` é medida a cada 5 minutos. Acima do limite o banco vira `read_only` (escritas falham; há evento e aviso ao time) e **volta ao normal ao baixar** do limite (apague dados). O motor sinaliza `quota_exceeded` (422) quando a cota é incompatível com o uso.

Para mudar a cota: `PATCH /v1/projects/{p}/databases/{s}` com `{"quota_mb": 2048}` (`databases:write`); a resposta é o banco (`quota_mb`, `size_mb`, `read_only`). `GET /v1/projects/{p}/databases` lista os bancos do projeto.

## 5. Rotacionar credencial

`POST /v1/projects/{p}/databases/{s}/rotate` (`databases:write`) gera senha nova e termina as sessões antigas. Os serviços dependentes são marcados "precisam de redeploy" (re-resolução): faça deploy deles.

```bash
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-pg-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pg-db-$SUF" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/rotate" \
  -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "postgres"}
```

## 6. Apagar

`DELETE /v1/projects/{p}/databases/{s}` (`databases:write`; `204`). Pela API de token a chamada não exige step-up (o painel exige); por padrão faz **backup final** antes (`{"final_backup": false}` no corpo desliga). Apagar é irreversível para os dados atuais; restaure do backup final se precisar ([Backup e restore](/bancos/backup-restore/)).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401` / `403` | Token ausente/sem escopo `databases:write`. Peça um token com o escopo. |
| `404 not_found` | Projeto ou banco inexistente **ou de outro time** (indistinguíveis). Confira os ids. |
| `409 name_taken` | Já existe um serviço com esse `name` no projeto (todo banco é um serviço). Use outro `name`. |
| `422 quota_exceeded` | Cota insuficiente para o uso atual. Apague dados ou peça cota maior. |
| `503 unavailable` | Nó de banco indisponível. Repita com backoff (a mesma `Idempotency-Key`). Persistindo, pare e avise uma pessoa. |
| `429 rate_limited` | Espere `Retry-After`. |

Tabela completa: [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/bancos/mariadb.md

# MariaDB

Um banco gerenciado é um **serviço** `kind=database` do projeto. Ele vive no nó de banco (outro host), **não** na rede privada do grupo: os apps o acessam pela URL com TLS. Escopo do token: `databases:write` (criar, apagar, rotacionar) e `projects:read` (ler). Veja [Tokens e escopos](/seguranca/tokens-e-escopos/).

## 1. Criar

`name` é o nome do serviço (`^[a-z][a-z0-9-]{0,30}$`, único no projeto; é o prefixo das referências `${{db.…}}`). `engine` é `postgres`, `mariadb` ou `sqlite`; `quota_mb` é a cota em MB.

```bash
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-mdb-$SUF\"}" | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mdb-db-$SUF" \
  -d '{"name": "db", "engine": "mariadb", "quota_mb": 1024}'
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "mariadb", "status": "provisioning", "quota_mb": 1024}
```

O banco nasce em `provisioning` e vira `ready`. Consulte `GET /v1/projects/$P/databases/{s}` com backoff (2 s, dobrando até 30 s, até uns 10 min) até o banco estar pronto antes de fazer deploy dos dependentes:

```bash
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-mdb-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mdb-db-$SUF" \
  -d '{"name": "db", "engine": "mariadb", "quota_mb": 1024}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  [ "$st" = ready ] && break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "mariadb", "status": "ready", "quota_mb": 1024, "read_only": false}
```

## 2. Variáveis entregues

Todas **sensíveis** (mascaradas em log e UI) e referenciáveis por qualquer serviço do grupo:

| Variável | Conteúdo |
|---|---|
| `DATABASE_URL` | `mysql://<papel>:<senha>@<public_host>:3306/<db>?ssl=true` |
| `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` | as mesmas peças, separadas |

O certificado do `public_host` é de CA pública (Let's Encrypt): `ssl=true` funciona sem instalar CA própria. Mantenha o TLS ligado; não o desative no cliente.

No app, use por referência (nunca copie o valor): `${{db.DATABASE_URL}}`. Veja [Conexão e referências](/bancos/conexao-e-referencias/).

Ler o valor em claro exige o escopo `env:reveal` num token criado com step-up (`GET …/variables?resolved=true`). Sem ele, o valor vem mascarado. As credenciais também saem de `POST /v1/projects/{p}/databases/{s}/credentials` (exige `env:reveal`): `{"credentials": [{"name": "DATABASE_URL", "value": "..."}, ...]}`.

## 3. Conectar de fora (diagnóstico)

Com as credenciais reveladas (cliente `mysql`/`mariadb`, TLS ligado):

```bash
mysql --ssl -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE" -e 'select 1'
```

## 4. Cota

`quota_mb` é medida a cada 5 minutos. Acima do limite o banco vira `read_only` (escritas falham; há evento e aviso ao time) e **volta ao normal ao baixar** do limite (apague dados). O motor sinaliza `quota_exceeded` (422) quando a cota é incompatível com o uso.

Para mudar a cota: `PATCH /v1/projects/{p}/databases/{s}` com `{"quota_mb": 2048}` (`databases:write`); a resposta é o banco (`quota_mb`, `size_mb`, `read_only`). `GET /v1/projects/{p}/databases` lista os bancos do projeto.

## 5. Rotacionar credencial

`POST /v1/projects/{p}/databases/{s}/rotate` (`databases:write`) gera senha nova e termina as sessões antigas. Os serviços dependentes são marcados "precisam de redeploy" (re-resolução): faça deploy deles.

```bash
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-mdb-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mdb-db-$SUF" \
  -d '{"name": "db", "engine": "mariadb", "quota_mb": 1024}' | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/rotate" \
  -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "mariadb"}
```

## 6. Apagar

`DELETE /v1/projects/{p}/databases/{s}` (`databases:write`; `204`). Pela API de token a chamada não exige step-up (o painel exige); por padrão faz **backup final** antes (`{"final_backup": false}` no corpo desliga). Apagar é irreversível para os dados atuais; restaure do backup final se precisar ([Backup e restore](/bancos/backup-restore/)).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401` / `403` | Token ausente/sem escopo `databases:write`. Peça um token com o escopo. |
| `404 not_found` | Projeto ou banco inexistente **ou de outro time** (indistinguíveis). Confira os ids. |
| `409 name_taken` | Já existe um serviço com esse `name` no projeto (todo banco é um serviço). Use outro `name`. |
| `422 quota_exceeded` | Cota insuficiente para o uso atual. Apague dados ou peça cota maior. |
| `503 unavailable` | Nó de banco indisponível. Repita com backoff (a mesma `Idempotency-Key`). Persistindo, pare e avise uma pessoa. |
| `429 rate_limited` | Espere `Retry-After`. |

Tabela completa: [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/bancos/sqlite.md

# SQLite (libSQL)

Um banco gerenciado é um **serviço** `kind=database` do projeto. Ele vive no nó de banco (outro host), **não** na rede privada do grupo: os apps o acessam pela URL com TLS. Escopo do token: `databases:write` (criar, apagar, rotacionar) e `projects:read` (ler). Veja [Tokens e escopos](/seguranca/tokens-e-escopos/).

## 1. Criar

`name` é o nome do serviço (`^[a-z][a-z0-9-]{0,30}$`, único no projeto; é o prefixo das referências `${{db.…}}`). `engine` é `postgres`, `mariadb` ou `sqlite`; `quota_mb` é a cota em MB.

```bash
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-sq-$SUF\"}" | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sq-db-$SUF" \
  -d '{"name": "db", "engine": "sqlite", "quota_mb": 1024}'
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "sqlite", "status": "provisioning", "quota_mb": 1024}
```

O banco nasce em `provisioning` e vira `ready`. Consulte `GET /v1/projects/$P/databases/{s}` com backoff (2 s, dobrando até 30 s, até uns 10 min) até o banco estar pronto antes de fazer deploy dos dependentes:

```bash
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-sq-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sq-db-$SUF" \
  -d '{"name": "db", "engine": "sqlite", "quota_mb": 1024}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  [ "$st" = ready ] && break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "sqlite", "status": "ready", "quota_mb": 1024, "read_only": false}
```

## 2. Variáveis entregues

Todas **sensíveis** (mascaradas em log e UI) e referenciáveis por qualquer serviço do grupo:

| Variável | Conteúdo |
|---|---|
| `LIBSQL_URL` | `libsql://…` do banco |
| `LIBSQL_AUTH_TOKEN` | token de acesso (JWT) do banco |
| `DATABASE_URL` | igual a `LIBSQL_URL` |

A conexão é por TLS; o cliente libSQL usa `LIBSQL_URL` + `LIBSQL_AUTH_TOKEN`.

No app, use por referência (nunca copie o valor): `${{db.DATABASE_URL}}`. Veja [Conexão e referências](/bancos/conexao-e-referencias/).

Ler o valor em claro exige o escopo `env:reveal` num token criado com step-up (`GET …/variables?resolved=true`). Sem ele, o valor vem mascarado. As credenciais também saem de `POST /v1/projects/{p}/databases/{s}/credentials` (exige `env:reveal`): `{"credentials": [{"name": "DATABASE_URL", "value": "..."}, ...]}`.

## 3. Conectar de fora (diagnóstico)

Com as credenciais reveladas, use o SDK libSQL da sua linguagem com `LIBSQL_URL` e `LIBSQL_AUTH_TOKEN` (ilustrativo):

```ts
// SDK libSQL: createClient({ url: process.env.LIBSQL_URL, authToken: process.env.LIBSQL_AUTH_TOKEN })
```

## 4. Cota

`quota_mb` é medida a cada 5 minutos. Acima do limite o banco vira `read_only` (escritas falham; há evento e aviso ao time) e **volta ao normal ao baixar** do limite (apague dados). O motor sinaliza `quota_exceeded` (422) quando a cota é incompatível com o uso.

Para mudar a cota: `PATCH /v1/projects/{p}/databases/{s}` com `{"quota_mb": 2048}` (`databases:write`); a resposta é o banco (`quota_mb`, `size_mb`, `read_only`). `GET /v1/projects/{p}/databases` lista os bancos do projeto.

## 5. Rotacionar credencial

`POST /v1/projects/{p}/databases/{s}/rotate` (`databases:write`) troca a chave de assinatura do banco: o `LIBSQL_AUTH_TOKEN` anterior passa a dar 401 na hora e um token novo é selado. A URL não muda. Os serviços dependentes são marcados "precisam de redeploy" (re-resolução): faça deploy deles.

```bash
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-sq-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sq-db-$SUF" \
  -d '{"name": "db", "engine": "sqlite", "quota_mb": 1024}' | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/rotate" \
  -H "$H"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "db", "kind": "database", "engine": "sqlite"}
```

## 6. Apagar

`DELETE /v1/projects/{p}/databases/{s}` (`databases:write`; `204`). Pela API de token a chamada não exige step-up (o painel exige); por padrão faz **backup final** antes (`{"final_backup": false}` no corpo desliga). Apagar é irreversível para os dados atuais; restaure do backup final se precisar ([Backup e restore](/bancos/backup-restore/)).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401` / `403` | Token ausente/sem escopo `databases:write`. Peça um token com o escopo. |
| `404 not_found` | Projeto ou banco inexistente **ou de outro time** (indistinguíveis). Confira os ids. |
| `409 name_taken` | Já existe um serviço com esse `name` no projeto (todo banco é um serviço). Use outro `name`. |
| `422 quota_exceeded` | Cota insuficiente para o uso atual. Apague dados ou peça cota maior. |
| `503 unavailable` | Nó de banco indisponível. Repita com backoff (a mesma `Idempotency-Key`). Persistindo, pare e avise uma pessoa. |
| `429 rate_limited` | Espere `Retry-After`. |

Tabela completa: [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/bancos/conexao-e-referencias.md

# Conexão e referências

O banco **não** entra na rede privada do grupo (`nbg-…`): ele fica no nó de banco e é acessado pela URL das variáveis, com TLS, no `public_host`. Por isso o app deve usar as variáveis entregues, nunca um hostname montado à mão.

## Variáveis referenciáveis

Prefixo = `name` do serviço-banco (aqui `db`):

| Motor | Referências |
|---|---|
| PostgreSQL | `${{db.DATABASE_URL}}`, `${{db.PGHOST}}`, `${{db.PGPORT}}`, `${{db.PGUSER}}`, `${{db.PGPASSWORD}}`, `${{db.PGDATABASE}}` |
| MariaDB | `${{db.DATABASE_URL}}`, `${{db.MYSQL_HOST}}`, `${{db.MYSQL_PORT}}`, `${{db.MYSQL_USER}}`, `${{db.MYSQL_PASSWORD}}`, `${{db.MYSQL_DATABASE}}` |
| SQLite | `${{db.LIBSQL_URL}}`, `${{db.LIBSQL_AUTH_TOKEN}}`, `${{db.DATABASE_URL}}` |

Todas são sensíveis: o valor resolvido de quem as referencia herda a sensibilidade e fica mascarado em log e UI (veja [Referência a valor sensível](/conectados/variaveis-e-referencias/#referência-a-valor-sensível)).

## Ligar o app ao banco

Defina no serviço do app uma variável cujo valor é a referência. A resolução acontece no **deploy**.

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

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/DATABASE_URL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "${{db.DATABASE_URL}}"}'
```
```json
{"name": "DATABASE_URL"}
```

O `POST` do deploy responde `422 unresolved_reference` se `db` não existir no projeto ou a variável não existir (`details.references` lista quais), e `422 reference_cycle` se as referências formarem ciclo. Corrija a referência e faça deploy de novo; não adianta repetir igual.

## Conexão com TLS

- PostgreSQL: mantenha `sslmode=verify-full` (já vem na `DATABASE_URL`); a CA é pública, não instale nada.
- MariaDB: `ssl=true` (já vem na `DATABASE_URL`).
- SQLite: `LIBSQL_URL` (TLS) + `LIBSQL_AUTH_TOKEN`.

## Como o serviço alcança o banco

O serviço conecta ao `public_host` do nó de banco (por exemplo `db1.<dominio>:5432`), saindo da rede do projeto pela internet pública, **sempre com TLS** (`sslmode=verify-full` no PostgreSQL: valide o certificado e o nome do host, com a CA pública, sem instalar nada). O nó de banco só aceita conexões vindas dos **IPs de saída da plataforma**: um cliente em outra origem (seu notebook, outro provedor) é recusado na rede, mesmo com a credencial certa. Cada banco tem a **sua própria credencial** (usuário e senha só dele, sem privilégios administrativos), entregue pelas referências acima. O acesso direto de fora da plataforma não é suportado: faça a consulta de dentro de um serviço do projeto. Detalhes de isolamento: [Isolamento](/seguranca/isolamento/#bancos-gerenciados).

## Quando o valor muda

Rotação de credencial, restore em SQLite ou restore para banco novo mudam o valor referenciado: os serviços dependentes ficam marcados "precisam de redeploy". Faça deploy deles ([Deploys e status](/operacao/deploys-e-status/)).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `422 unresolved_reference` no deploy | Variável ou serviço referenciado não existe: confira o nome do serviço-banco e a variável da tabela acima. |
| `422 reference_cycle` no deploy | Remova a referência circular entre variáveis. |
| app não conecta (TLS/credencial) | Houve rotação? Faça deploy do app para re-resolver. |
| `404 not_found` | Projeto/serviço inexistente ou de outro time. |

Veja [Variáveis e referências](/conectados/variaveis-e-referencias/) e [Erros](/erros/tabela/).

Se um app usa um driver de banco (PostgreSQL, MySQL, MongoDB) mas nenhum banco está ligado, a plataforma detecta e **sugere** criar um banco gerenciado e injetar a referência `${{db.DATABASE_URL}}` automaticamente — sem criar nada sem a sua autorização. Veja [Sugestões de persistência](/conectados/sugestoes-de-persistencia/).

---

URL: https://docs.nebularws.com/bancos/backup-restore.md

# Backup e restore

Escopo: `databases:write`. Substitua `$P` (projeto) e `$DB` (serviço-banco) pelos ids.

## Política

- Backup **diário** automático: retenção de 7 diários + 4 semanais.
- Backup **sob demanda** quando quiser (antes de uma migration arriscada, por exemplo).
- Apagar o banco faz um backup final por padrão.

## Criar um backup

```bash
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\": \"bk-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)
# o banco nasce em provisioning: espere ficar ready antes de pedir backup
for i in $(seq 1 40); do
  [ "$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)" = ready ] && break
  sleep 2
done

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/backups" \
  -H "$H" \
  -H "Idempotency-Key: backup-$DB-$(date +%Y%m%d%H%M)-$RANDOM"
```
```json
{"backup_id": "b_01J9ZK5Q", "job_id": "j_01J9ZK5R"}
```

A resposta é `202`: o backup é assíncrono. Guarde `backup_id`.

## Listar backups

Paginação por cursor (`next_cursor` / `has_more`). Cada item tem `id`, `at`, `size`, `status`.

```bash
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\": \"bk-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)
# o banco nasce em provisioning: espere ficar ready antes de pedir backup
for i in $(seq 1 40); do
  [ "$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)" = ready ] && break
  sleep 2
done
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/backups" -H "$H" >/dev/null

curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB/backups" \
  -H "$H"
```
```json
{"items": [{"id": "b_01J9ZK5Q", "at": "2026-10-10T03:00:00Z", "size": 1048576, "status": "running"}], "next_cursor": null, "has_more": false}
```

O item nasce `running` e vira `done`. Espere o backup concluir antes de usá-lo (restaurar um backup que ainda roda responde `409 backup_not_ready`): consulte o job com `GET /v1/projects/{p}/databases/{s}/jobs/{job_id}` (`status`: `queued`, `running`, `done`, `failed`; no `failed` vem `error` com `code` e `message`), com backoff de 2 s dobrando até 30 s, teto de uns 10 min.

## Restore

`target`:

- `"new"` (padrão): restaura para um banco novo; informe `new_db_name`. Seguro, não toca nos dados atuais.
- `"same"`: sobrescreve o banco atual. Destrutivo para os dados atuais: no painel exige step-up (confirmação recente de identidade); pela API de token vale o escopo `databases:write`, então só use com autorização explícita de uma pessoa.

```bash
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\": \"bk-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)
# o banco nasce em provisioning: espere ficar ready antes de pedir backup
for i in $(seq 1 40); do
  [ "$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB" -H "$H" | jq -r .status)" = ready ] && break
  sleep 2
done
R=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/backups" -H "$H")
B=$(echo "$R" | jq -r .backup_id); J=$(echo "$R" | jq -r .job_id)

# espera o job do backup concluir (backoff 2 s, dobrando até 30 s)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/databases/$DB/jobs/$J" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  [ "$st" = done ] && break
  case "$st" in failed) exit 1 ;; esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = done ]

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases/$DB/restore" \
  -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: restore-$DB-$B" \
  -d "{\"backup_id\": \"$B\", \"target\": \"new\", \"new_db_name\": \"n_restaurado\"}"
```
```json
{"job_id": "j_01J9ZK5S"}
```

Resposta `202`. O restore é assíncrono: consulte o resultado com backoff até concluir.

## O que muda em cada motor

| Motor | Efeito do restore |
|---|---|
| PostgreSQL / MariaDB, `new` | cria um banco extra na mesma instância; a plataforma monta a `DATABASE_URL` do banco novo (mesmo papel e senha, outro nome de banco). Aponte o app para ele quando validar. |
| PostgreSQL / MariaDB, `same` | sobrescreve o banco atual; as variáveis não mudam. |
| SQLite, `new` ou `same` | **a URL e o token MUDAM em todo restore** (o namespace antigo é removido no `same`). A plataforma sela o token novo, atualiza `LIBSQL_URL`/`LIBSQL_AUTH_TOKEN` e marca os dependentes para redeploy: faça deploy deles. |

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401` / `403` | Falta `databases:write`. Pare e peça a uma pessoa. |
| `409 backup_not_ready` | O backup ainda não terminou (job `running`): espere o job e repita. |
| `404 not_found` | Banco ou `backup_id` inexistente ou de outro time. Liste os backups de novo. |
| `409` | Há outra operação em andamento no banco, ou `new_db_name` já existe. Espere ou troque o nome. |
| `422 quota_exceeded` | O restore não cabe na cota. Aumente a cota ou apague dados. |
| `503 unavailable` | Repita com backoff e a mesma `Idempotency-Key`; persistindo, pare e avise. |
| `429 rate_limited` | Espere `Retry-After`. |

Veja [Erros](/erros/tabela/) e [Rate limit e retry](/erros/rate-limit-e-retry/).

---

URL: https://docs.nebularws.com/bancos/migracoes.md

# Migrações

A plataforma não executa migrations por você: o **seu app** (ou uma ferramenta de migrations da sua linguagem) as aplica usando a `DATABASE_URL` entregue ([Conexão e referências](/bancos/conexao-e-referencias/)).

## Regras

- **Toda migration tem `down`** e foi testada (suba e desça em ambiente local antes do deploy).
- Mudanças destrutivas em dois passos (expand-contract): adicione o novo, migre o código, só depois remova o antigo. Nunca `DROP` ou renomeação destrutiva num passo só.
- Faça um [backup sob demanda](/bancos/backup-restore/) antes de uma migration arriscada.
- Migrations usam SQL parametrizado e a mesma conexão TLS (`sslmode=verify-full`, `ssl=true` ou `LIBSQL_URL`).
- Cota: um banco acima de `quota_mb` fica `read_only`; migration que cresce dados pode falhar por isso.

## Onde rodar

Rode as migrations na **inicialização do serviço**, antes de aceitar tráfego, de forma idempotente (a ferramenta guarda a versão aplicada). Com mais de uma instância subindo, use o lock da própria ferramenta de migrations. Se a migration falha, o app deve sair com erro: o deploy não fica `ready` e o rollback ([Rollback](/operacao/rollback/)) volta ao deploy anterior.

Atenção: o rollback do deploy **não** desfaz o schema. Se o código antigo for incompatível com a migration já aplicada, rode a `down` ou restaure um backup.

## Se algo falhar

| Sintoma | O que fazer |
|---|---|
| deploy não chega a `ready` por erro de migration | Leia o log de build/runtime ([Logs](/operacao/logs/)), corrija a migration e faça novo deploy. |
| `read_only` / erro de escrita | Cota estourada: libere espaço; volta ao normal ao baixar do limite. |
| `503 unavailable` ao conectar | Repita com backoff; o app não deve derrubar o deploy por indisponibilidade transitória do banco além do tempo de retry. |

---

URL: https://docs.nebularws.com/conectados/front-back-db.md

# Front, back e banco

Objetivo: um projeto com três serviços.

```mermaid
flowchart LR
  U[Internet] --> W[web: Next.js, public]
  W -- API_URL=${{api.PRIVATE_URL}} --> A[api: Go, private]
  A -- DATABASE_URL=${{db.DATABASE_URL}} --> D[(db: Postgres)]
```

Escopos do token: `projects:write`, `databases:write`, `env:write`, `deploy`, `projects:read`. As variáveis do shell (`H`, `P`, `DB`, `API`, `WEB`) vivem no mesmo bloco; ao repetir só um passo, recapture os ids com `GET` (lista de projetos e serviços). Os ids são opacos (ULID de 26 caracteres); os exemplos mostram o formato real.

O caminho completo para código **próprio** é: banco, back, front (passos 1 a 3), **enviar o código de cada serviço** (passo 4), **deploy do grupo** (passo 5) e **polling** (passo 6). Se você já tem imagens publicadas, use a variante com imagens, no fim do passo 5.

## 1. Criar o projeto e o banco

`POST .../databases` cria um serviço `kind=database`. Os motores são `postgres`, `mariadb`, `sqlite`; `quota_mb` é a cota do banco.

```bash
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\": \"loja-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fbd-db-$SUF" \
  -d '{"name": "db", "quota_mb": 1024, "engine": "postgres"}'
```
```json
{"id": "01j9zkff8y1dmcwa49fanx9qak", "name": "db", "kind": "database", "engine": "postgres", "status": "provisioning"}
```

Em erro: `503 unavailable` (repita com backoff), `422 quota_exceeded` (reduza `quota_mb` ou veja [Limites e cotas](/operacao/limites-e-cotas/)), `403` (falta `databases:write`).

## 2. Criar o back (Go, privado) e ligar ao banco

O back não tem rota pública (`private`); o `DATABASE_URL` vem do banco por referência.

```bash
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" \
  -H "Idempotency-Key: fbd2-proj-$SUF" -d "{\"name\": \"loja2-$SUF\"}" | jq -r .id)
API=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fbd2-api-$SUF" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080,
       "source": {"type": "upload"}, "build": {"builder": "go"}, "healthcheck_path": "/healthz"}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$API/variables/DATABASE_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{db.DATABASE_URL}}"}'
```

A referência só é resolvida no deploy. Se `db` não existir no projeto, o `POST` do deploy responde `422 unresolved_reference` (nada é criado) com `details.references`.

## 3. Criar o front (Next.js, público) apontando para o back

Todo projeto já nasce com um serviço `web`, **público** e com `slug` e `public_url` gerados (por exemplo `web-br5pg0`): o `PATCH` abaixo o adapta (fonte, build, porta) em vez de criar outro. Para um front **privado** (só alcançável na rede do projeto), mande `{"visibility": "private"}`; o `slug` e a URL pública deixam de existir. O `PATCH` com `"visibility": "public"` e sem `slug` devolve o serviço público com um `slug` derivado do nome.

```bash
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" \
  -H "Idempotency-Key: fbd3-proj-$SUF" -d "{\"name\": \"loja3-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080, "source": {"type": "upload"}, "build": {"builder": "go"}}' >/dev/null
WEB=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"loja3-$SUF\", \"port\": 3000,
       \"source\": {\"type\": \"upload\"}, \"build\": {\"builder\": \"node\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$WEB/variables/API_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{api.PRIVATE_URL}}"}'
```

No código do Next.js, chame o back **no servidor** (route handler ou server component) com `process.env.API_URL`: a URL é privada e não funciona no browser. Segredos nunca em variável `NEXT_PUBLIC_*`.

## 4. Enviar o código (upload) e implantar cada serviço

Serviço com `source.type = "upload"` só tem o que implantar depois que **recebe um arquivo**. Não existe rota de "enviar sem implantar": o envio é o próprio deploy do serviço (`POST .../services/{s}/deployments` com `multipart/form-data`, campo `file`, `.tar.gz` ou `.zip`). Por isso a ordem é:

1. espere o banco ficar `ready` (`GET .../databases/{db}`);
2. envie o código do **back** e espere `ready`;
3. envie o código do **front** e espere `ready`.

O exemplo cria tudo do zero com dois pacotes mínimos (troque pelos seus). O arquivo recebido fica guardado como a fonte atual do serviço.

```bash
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
espera() { # espera() URL: polling com backoff até ready; falha em qualquer terminal ruim
  local delay=2 st
  for i in $(seq 1 40); do
    st=$(curl -sS "$1" -H "$H" | jq -r .status)
    case "$st" in
      ready) return 0 ;;
      failed|blocked|canceled|superseded) echo "terminou em $st" >&2; return 1 ;;
    esac
    sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
  done
  return 1
}
API_URL_BASE="$NEBULAR_API/v1/projects"

P=$(curl -sS -X POST "$API_URL_BASE" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"loja7-$SUF\"}" | jq -r .id)
DB=$(curl -sS -X POST "$API_URL_BASE/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fbd7-db-$SUF" -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)
API=$(curl -sS -X POST "$API_URL_BASE/$P/services" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "api", "visibility": "private", "port": 8080, "source": {"type": "upload"},
       "build": {"builder": "go"}, "healthcheck_path": "/healthz"}' | jq -r .id)
WEB=$(curl -sS -X PATCH "$API_URL_BASE/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"port": 3000, "source": {"type": "upload"}, "build": {"builder": "node"}}' | jq -r .id)
curl -sS -X PUT "$API_URL_BASE/$P/services/$API/variables/DATABASE_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{db.DATABASE_URL}}"}' >/dev/null
curl -sS -X PUT "$API_URL_BASE/$P/services/$WEB/variables/API_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{api.PRIVATE_URL}}"}' >/dev/null

# pacotes mínimos (no uso real: o código do seu back e do seu front)
T=$(mktemp -d)
printf 'module api\n\ngo 1.22\n' > "$T/go.mod"
printf 'package main\n\nfunc main() {}\n' > "$T/main.go"
tar -czf "$T/api.tgz" -C "$T" go.mod main.go
printf '{"name":"web","scripts":{"start":"node server.js"}}\n' > "$T/package.json"
printf 'require("http").createServer((q,r)=>r.end("ok")).listen(3000)\n' > "$T/server.js"
tar -czf "$T/web.tgz" -C "$T" package.json server.js

espera "$API_URL_BASE/$P/databases/$DB"
D=$(curl -sS -X POST "$API_URL_BASE/$P/services/$API/deployments" -H "$H" \
  -H "Idempotency-Key: fbd7-api-$SUF" -F "file=@$T/api.tgz" | jq -r .id)
espera "$API_URL_BASE/$P/services/$API/deployments/$D"
D=$(curl -sS -X POST "$API_URL_BASE/$P/services/$WEB/deployments" -H "$H" \
  -H "Idempotency-Key: fbd7-web-$SUF" -F "file=@$T/web.tgz" | jq -r .id)
espera "$API_URL_BASE/$P/services/$WEB/deployments/$D"
curl -sS "$API_URL_BASE/$P/services/$WEB/deployments/$D" -H "$H"
```

Ao enviar o arquivo, o `source_ref` do deploy mostra `upload:<nome-do-arquivo>`. Em erro: `400 invalid_request` (arquivo vazio, grande demais ou sem o campo `file`), `409 deploy_in_progress` (já há um deploy do serviço rodando: acompanhe-o), `422 unresolved_reference` (a variável aponta para algo que não existe).

## 5. Deploy do grupo

`POST /v1/projects/{p}/deploy` reimplanta todos os serviços em ordem topológica das referências: `db`, depois `api`, depois `web`. Use-o **depois** do passo 4, por exemplo após mudar uma variável compartilhada ou referenciada. As regras para serviços `upload`:

- **Já recebeu um arquivo antes**: o grupo **reimplanta o último arquivo enviado** (o item vem com `deployment_id`).
- **Nunca recebeu arquivo (sem fonte)**: o item vem `skipped`, sem `deployment_id` e com `reason` (`sem fonte: nenhum arquivo foi enviado para este serviço`). O resto do grupo segue; se **tudo** é `skipped`, o grupo termina `ready` sem implantar nada. Citar o serviço em `services` não o pula: sem fonte, o deploy dele falha.
- Se o build de um serviço falhar, os dependentes ficam `blocked`; os já ativos continuam no ar.

O corpo é `{}` (ou `{"services": ["api", "web"]}` para um subconjunto) com `Content-Type: application/json`; também é aceito sem corpo e sem `Content-Type` (veja [Convenções](/comecar/convencoes-da-api/)).

```bash
# projeto novo: o web padrão é upload e ainda não recebeu arquivo
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\": \"loja8-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fbd8-grp-$SUF" -d '{}'
```
```json
{"id": "01j9zk0dst6zttk3bamcgshaxf", "project_id": "01j9zkk07fhzv5zsmn996cdwpb", "status": "ready", "items": [{"service_id": "01j9zkff8y1dmcwa49fanx9qak", "status": "skipped", "layer": 0, "reason": "sem fonte: nenhum arquivo foi enviado para este serviço"}]}
```

Em erro: `unresolved_reference` ou `reference_cycle` (corrija as variáveis, veja [Variáveis e referências](/conectados/variaveis-e-referencias/)), `403` (falta `deploy`), `429` (espere `Retry-After`).

### Variante com imagens publicadas

Se o back e o front já são imagens, o grupo dispara tudo de uma vez, sem passo de upload. Fixe a versão por digest (`repo:tag@sha256:...`, veja [Imagem pública](/guia/imagem-publica/#fixar-por-digest-e-como-obter-o-digest)); o exemplo usa tags só para ser curto.

```bash
# preparo (passos 1 a 3): banco, back e front do projeto
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\": \"loja4-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/databases" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' >/dev/null
API=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "api", "visibility": "private", "port": 8080,
       "source": {"type": "image", "ref": "ghcr.io/org/api:1.0"}, "healthcheck_path": "/healthz"}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$API/variables/DATABASE_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{db.DATABASE_URL}}"}' >/dev/null
WEB=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"loja4-$SUF\", \"port\": 3000,
       \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/web:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$WEB/variables/API_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{api.PRIVATE_URL}}"}' >/dev/null

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" \
  -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fbd-deploy-$SUF" -d '{}'
```
```json
{"id": "01j9zk0dst6zttk3bamcgshaxf", "project_id": "01j9zkk07fhzv5zsmn996cdwpb", "status": "running", "items": [{"service_id": "01j9zkff8y1dmcwa49fanx9qak", "deployment_id": "01j9zkxg2h4dbcfe129fwypfsb", "status": "queued", "layer": 0}]}
```

## 6. Esperar com backoff (um GET para o grupo todo)

Acompanhe o **grupo** com `GET /v1/projects/{p}/group-deployments/{g}` (`G` = `id` devolvido pelo `POST .../deploy`): um único `GET` mostra o `status` do grupo (`running` até terminar; depois `ready`, `failed`, `canceled` ou `superseded`) e o `status` de cada item (`queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `skipped`). Não é preciso listar os deploys de cada serviço. Para o motivo de uma falha, pegue o `deployment_id` do item `failed` e leia o [log de build](/operacao/logs/).

```bash
# preparo: projeto com o front (imagem) e um deploy de grupo em andamento
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\": \"fbd5-$SUF\"}" | jq -r .id)
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' >/dev/null
G=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/deploy" -H "$H" \
  -H "Content-Type: application/json" -H "Idempotency-Key: fbd5-grp-$SUF" -d '{}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/group-deployments/$G" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|canceled|superseded) echo "grupo terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]
curl -sS "$NEBULAR_API/v1/projects/$P/group-deployments/$G" -H "$H"
```

Estado `failed` no grupo: algum item falhou; leia o log de build dele. Item `blocked`: um serviço do qual ele depende falhou; corrija o dependente primeiro. Para acompanhar **um** serviço isolado, use `GET .../services/{s}/deployments/{d}` ([Deploys e status](/operacao/deploys-e-status/)).

## 7. Verificar

```bash
curl -sS -o /dev/null -w '%{http_code}\n' "https://loja3-1760000000.nebularws.com/"
```

Se der erro `5xx`, leia o [log de runtime](/operacao/logs/) do `web` e do `api`. Para voltar a versão, [rollback](/operacao/rollback/).

## Ver também

[Rede privada](/conectados/rede-privada/), [PostgreSQL](/bancos/postgres/), [Next.js](/guia/nodejs-next/), [Go](/guia/go/).

---

URL: https://docs.nebularws.com/conectados/variaveis-e-referencias.md

# Variáveis e referências

Escopos: `env:read`, `env:write`, `env:reveal` ([Tokens e escopos](/seguranca/tokens-e-escopos/)).

## Escopos de variável

- **`service`**: vale só para um serviço. Rota: `/v1/projects/{p}/services/{s}/variables[/{name}]`.
- **`shared`**: guardada no projeto. Rota: `/v1/projects/{p}/shared-variables[/{name}]`. **Ela não entra sozinha no ambiente de nenhum serviço**: só chega a um serviço que a referencie com `${{shared.NOME}}` (veja abaixo).

Valor literal ou com **referências**: `${{<servico>.<VAR>}}` (variável de outro serviço do projeto) e `${{shared.VAR}}` (variável compartilhada). `shared` é nome reservado: nenhum serviço pode se chamar assim.

## Definir, ler e apagar

```bash
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: var-proj-$SUF" -d "{\"name\": \"vars-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: var-svc-$SUF" \
  -d "{\"name\": \"api\", \"kind\": \"app\", \"visibility\": \"private\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/api:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/LOG_LEVEL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "info"}'
```
```json
{"name": "LOG_LEVEL", "value": "info", "sensitive": false, "needs_redeploy": []}
```

O corpo do `PUT` é `{"value": "...", "sensitive": true|false}` (`sensitive` é opcional; uma variável já sensível nunca volta a ser não sensível). A resposta traz a variável e `needs_redeploy`, a lista de serviços que precisam de novo deploy para ver o valor (vazia quando nenhum serviço usa a variável). Variável **sensível**: o `PUT` nunca devolve o valor (`"value": null`) e as leituras só o mostram a um token com `env:reveal`; sem ele, `value` vem `null` e `sensitive` vem `true`.

Para definir várias de uma vez (tudo ou nada, de 1 a 200 itens), use `PUT .../variables` com `{"variables": [{"name": "A", "value": "1"}, {"name": "B", "value": "2", "sensitive": true}]}`; a resposta é `{"items": [...], "needs_redeploy": [...]}`. `GET .../variables?resolved=true` devolve as variáveis já com as referências expandidas e as automáticas (exige `env:reveal`).

Variável compartilhada do projeto:

```bash
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: var2-proj-$SUF" -d "{\"name\": \"vars2-$SUF\"}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/shared-variables/REGION" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "br"}'
```

Para que o serviço enxergue a variável compartilhada `REGION`, crie nele uma variável própria que a referencie (o nome pode ser o mesmo ou outro). Sem essa referência, `REGION` não aparece no ambiente do serviço:

```json
PUT /v1/projects/{p}/services/{s}/variables/REGION
{"value": "${{shared.REGION}}"}
```

Referência a outro serviço (o front lê a URL privada do back):

```bash
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" \
  -H "Idempotency-Key: var3-proj-$SUF" -d "{\"name\": \"vars3-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080, "source": {"type": "image", "ref": "ghcr.io/org/api:1.0"}}' >/dev/null
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"vars3-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/web:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/API_URL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "${{api.PRIVATE_URL}}"}'
```

Listar (valores sensíveis vêm mascarados sem `env:reveal`) e apagar:

```bash
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" \
  -H "Idempotency-Key: var4-proj-$SUF" -d "{\"name\": \"var4-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: var4-svc-$SUF" \
  -d '{"name": "app", "kind": "app", "visibility": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/LOG_LEVEL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "info"}'
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/variables" -H "$H"
curl -sS -X DELETE "$NEBULAR_API/v1/projects/$P/services/$S/variables/LOG_LEVEL" -H "$H"
```

## Variáveis automáticas (resolvíveis por referência)

Todo serviço ganha, sem você definir:

| Variável | Valor |
|---|---|
| `NEBULAR_SERVICE_NAME` | o `name` do serviço |
| `PORT` | a porta interna |
| `PRIVATE_HOST` | `<name>` (hostname na [rede privada](/conectados/rede-privada/)) |
| `PRIVATE_URL` | `http://<name>:<port>` |
| `PUBLIC_URL` | URL pública, se o serviço é `public`; senão vazio |
| `PUBLIC_DOMAIN` | domínio público do serviço |

Serviços de banco também expõem `DATABASE_URL` e as variáveis do motor ([Conexão e referências](/bancos/conexao-e-referencias/)). Exemplo: `${{api.PRIVATE_URL}}`, `${{db.DATABASE_URL}}`.

Se um app precisa de um banco ou de disco persistente que ainda não existe, a plataforma detecta e sugere criar o recurso (e, no caso de banco, injetar a referência `${{db.DATABASE_URL}}`), sempre esperando sua autorização: veja [Sugestões de persistência](/conectados/sugestoes-de-persistencia/).

## Como a resolução funciona

- Acontece **no deploy**, por serviço. Quem é referenciado sobe antes (ordem topológica no deploy de grupo).
- Referência a variável ou serviço inexistente: o `POST` do deploy responde `422 unresolved_reference` e nada é criado; `details.references` lista os nomes com problema. O `PUT` da variável aceita a referência: o erro só aparece no deploy.
- Referências em ciclo: `422 reference_cycle` (também com `details.references`).
- Outros erros de resolução presentes na API: `invalid_reference` (um `${{...}}` que não é da forma `escopo.VAR`), `reference_too_deep` (aninhamento acima de 16 níveis) e `value_too_large` (valor expandido acima de 64 KiB ou ambiente acima de 256 KiB).
- Valor resolvido **herda a sensibilidade** do que foi referenciado (veja a próxima seção).
- **Re-resolução**: mudar um valor referenciado marca os dependentes como "precisam de redeploy". Faça um novo deploy dos dependentes (ou ative `auto_deploy`).

## Referência a valor sensível

Uma variável cujo valor é uma referência (`DATABASE_URL = ${{db.DATABASE_URL}}`) guarda o **texto da referência**, não o segredo. Por isso:

- O `PUT` pode responder `"sensitive": false` e a leitura sem `resolved` mostra o texto `${{db.DATABASE_URL}}`: nada de segredo trafega ali. Se quiser a variável tratada como sensível já na definição, envie `"sensitive": true` no `PUT` (a resposta volta com `value: null`).
- O **valor resolvido** herda a sensibilidade de quem foi referenciado: `GET ...?resolved=true` mostra `DATABASE_URL` com `"sensitive": true`, e o valor fica mascarado em log e painel.
- Essa leitura resolvida (e `env:reveal` em geral) entrega o segredo **em claro** ao token com o escopo `env:reveal`, que precisa ser pedido explicitamente ao criar o token ([Tokens e escopos](/seguranca/tokens-e-escopos/)). Sem o escopo, `resolved=true` dá `403`. Trate a resposta como segredo: não a registre em log nem a cole em chat.
- `depends_on` do serviço (usado para a ordem do deploy de grupo) é calculado das referências gravadas: o serviço `api` passa a listar `["db"]` na leitura do serviço assim que a variável com `${{db...}}` existe. A resposta de **criação** do serviço, anterior à variável, vem com `depends_on` vazio.

## Ler valores resolvidos

`GET .../variables?resolved=true` devolve os valores já expandidos. Exige o escopo `env:reveal` (token criado com step-up) e devolve valores sensíveis em claro.

```bash
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\": \"var5-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/LOG_LEVEL" -H "$H" \
  -H "Content-Type: application/json" -d '{"value": "info"}' >/dev/null

curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/variables?resolved=true" \
  -H "$H"
```
```json
{"items": [{"name": "LOG_LEVEL", "value": "info", "sensitive": false}], "next_cursor": null, "has_more": false}
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `403 forbidden` | Falta `env:write` (escrever), `env:read` (ler) ou `env:reveal` (`resolved=true`). Peça token novo. |
| `404 not_found` | Projeto, serviço ou variável inexistente ou fora do seu acesso. |
| `422 unresolved_reference` no deploy | Crie a variável/serviço citado ou corrija o nome na referência; redeploy. |
| `422 reference_cycle` no deploy | Quebre o ciclo (A referencia B que referencia A). |
| `400 invalid_request` | Nome ou valor inválido: corrija. |

---

URL: https://docs.nebularws.com/conectados/rede-privada.md

# Rede privada

## Regras

- Serviços do **mesmo projeto** ficam numa rede própria e se resolvem pelo `name` do serviço (DNS interno). O serviço `api` é alcançável por `api`, na porta do serviço.
- Serviços de **projetos diferentes nunca se alcançam**.
- `visibility: "private"` = **sem rota pública**: o proxy não publica e o serviço não recebe `slug`. Só os outros serviços do projeto o alcançam.
- Use as variáveis automáticas em vez de montar a URL: `${{api.PRIVATE_URL}}` (`http://api:8080`) ou `${{api.PRIVATE_HOST}}` + `${{api.PORT}}`. Veja [Variáveis e referências](/conectados/variaveis-e-referencias/).
- **Bancos gerenciados não ficam na rede do projeto**: moram num nó de banco e são acessados pela URL das variáveis (`DATABASE_URL` etc.), com TLS. Veja [Conexão e referências](/bancos/conexao-e-referencias/).
- Tráfego do serviço para a internet segue as regras de [Isolamento](/seguranca/isolamento/).

## Criar um serviço privado

```bash
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" \
  -H "Idempotency-Key: rp-proj-$SUF" -d "{\"name\": \"rede-$SUF\"}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: rp-api-$SUF" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080, "source": {"type": "image", "ref": "ghcr.io/org/api:1.0"}}'
```
```json
{"id": "01j9zkjxrzywfreswk9kf9r1z7", "name": "api", "kind": "app", "visibility": "private", "port": 8080}
```

No outro serviço do projeto, defina `API_URL` como `${{api.PRIVATE_URL}}` e chame `$API_URL/...` do código. Receita completa: [Front, back e banco](/conectados/front-back-db/).

## Se algo falhar

| Sintoma | O que fazer |
|---|---|
| O front não alcança o back | Confira o `port` do back (precisa bater com a porta em que o processo escuta), o `name` usado no hostname e se ambos estão no mesmo projeto. |
| `422 unresolved_reference` no deploy | O serviço referenciado não existe no projeto ou o nome está errado. |
| Quer acessar o serviço privado de fora | Não é possível; torne-o `public` (com `slug`) via `PATCH`, ou exponha só o front. |

---

URL: https://docs.nebularws.com/conectados/volumes.md

# Volumes

Escopo: `volumes:write` (e `projects:read` para ler).

## Regras

- **1 volume por serviço** neste ciclo.
- `mount_path`: absoluto, não pode ser `/`, nem `/proc`, `/sys`, `/dev`, `/etc`.
- `size_gb`: de 1 a 50.
- O sistema de arquivos do serviço é somente leitura; o volume (e `/tmp`, 64 MB) são os únicos graváveis.
- **Sobrevive a redeploy.** O redeploy recria a aplicação, nunca os dados do volume.
- **Apagar** pede confirmação de identidade (step-up) **só no painel**. Com token de API, o escopo `volumes:write` é a autorização: o `DELETE` não exige step-up.

## Criar (ou substituir) o volume

```bash
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" \
  -H "Idempotency-Key: vol-proj-$SUF" -d "{\"name\": \"vol-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol-svc-$SUF" \
  -d "{\"name\": \"app\", \"kind\": \"app\", \"visibility\": \"private\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{"mount_path": "/data", "size_gb": 5}'
```
```json
{"mount_path": "/data", "size_gb": 5}
```

O volume passa a existir no próximo deploy do serviço.

## Ler e apagar

```bash
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" \
  -H "Idempotency-Key: vol2-proj-$SUF" -d "{\"name\": \"vol2-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol2-svc-$SUF" \
  -d '{"name": "app", "kind": "app", "visibility": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H" \
  -H "Content-Type: application/json" -d '{"mount_path": "/data", "size_gb": 5}' >/dev/null
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H"
```
```json
{"mount_path": "/data", "size_gb": 5}
```

Apagar (`DELETE`, resposta `204`, irreversível) exige o escopo `volumes:write`; o step-up vale só no painel:

```text
DELETE /v1/projects/{p}/services/{s}/volume   (Authorization: Bearer $NEBULAR_TOKEN)
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | `mount_path` proibido ou `size_gb` fora de 1..50: corrija. |
| `403 forbidden` | Falta `volumes:write`. |
| `404 not_found` | Projeto/serviço inexistente ou sem acesso; ou o serviço não tem volume (no `GET`/`DELETE`). |
| `quota_exceeded` | Limite de armazenamento do time: veja [Limites e cotas](/operacao/limites-e-cotas/). |

---

URL: https://docs.nebularws.com/conectados/sugestoes-de-persistencia.md

# Sugestões de persistência

A plataforma observa seus apps e, quando percebe que um deles **precisa guardar dados mas não tem onde**, cria uma **sugestão**: uma mensagem curta explicando o problema e oferecendo a solução. A plataforma **nunca cria o recurso sozinha** — ela sugere e **espera você autorizar**, seja uma pessoa no painel ou um agent pela API. É o mesmo princípio em todo lugar: a Nebular detecta, propõe e só age com sua permissão.

## Quando uma sugestão aparece

Dois gatilhos geram sugestões:

1. **Detecção no build.** Ao preparar o deploy, a plataforma olha as dependências do app (o driver de banco ou o ORM que ele usa) e deduz o tipo de persistência que ele vai querer. Por exemplo: um app Node com `better-sqlite3`, ou um app Go com `modernc.org/sqlite`, embarca um banco SQLite e vai precisar de disco persistente.
2. **Falha no deploy (sinal mais preciso).** Quando o app sobe e quebra por falta de persistência, o erro diz exatamente o que faltou:
   - **`activate_readonly_write`**: o app tentou gravar num caminho somente-leitura (por exemplo `/app/data`). A sugestão já vem com o caminho exato.
   - **Conexão recusada a um banco** (`activate_app_crashed` cujo log mostra "connection refused" numa porta de banco) e o serviço não tem banco ligado.
   - **`unresolved_reference`**: o deploy aponta para um serviço de banco que não existe.

A sugestão **não atrapalha o deploy**: ela é informativa e fica guardada até você aceitar ou descartar. Se o recurso continua faltando, o deploy segue falhando com a mesma mensagem de sempre — nada é escondido nem quebrado.

## As duas soluções: volume ou banco

A diferença mais importante é **o que o app precisa**:

- **SQLite embarcado → volume.** O app já tem o banco dentro dele (um arquivo SQLite); só falta um **disco que sobreviva aos deploys**. A sugestão oferece criar um [volume](/conectados/volumes/) no caminho onde o app grava (por exemplo `/app/data`). Nada muda no código do app.
- **Driver externo (PostgreSQL, MySQL, MongoDB) → banco gerenciado.** O app fala com um banco que roda **fora** dele e que ainda não existe. A sugestão oferece criar um [banco gerenciado](/bancos/postgres/) e **ligar automaticamente** com a referência `${{<db>.DATABASE_URL}}` (onde `<db>` é o nome do serviço-banco criado). Veja como essa ligação funciona em [Conexão e referências](/bancos/conexao-e-referencias/).

Em ambos os casos a Nebular **corrige a si mesma** para aceitar o app como ele é: ela nunca edita o código do seu app.

## A plataforma nunca cria sozinha

Toda sugestão nasce no estado "sugerida" e fica parada até uma decisão:

- **Aceitar** cria o recurso (volume ou banco) e o liga ao serviço. O próximo deploy já usa.
- **Descartar** arquiva a sugestão. Ela não volta a nascer pelo mesmo sinal na mesma janela (sem spam).

Quem decide é **você**: uma pessoa no painel ou um agent pela API. Enquanto ninguém autoriza, nada é criado e nenhum dado é tocado.

## Como um agent lê as sugestões

Liste as sugestões abertas de um projeto com o escopo `projects:read` ([Tokens e escopos](/seguranca/tokens-e-escopos/)):

```bash
curl -sS "$NEBULAR_API/v1/projects/$P/suggestions" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```

Cada item traz o diagnóstico já pronto para mostrar a um humano, no campo `detail`:

```json
{
  "items": [
    {
      "id": "01j9zksf51s25jd7735q8fefyf",
      "service_id": "01j9zktb8c3m0xr4v6p2n1qd7e",
      "service_name": "polylang",
      "project_id": "01j9zkt0a2b3c4d5e6f7g8h9jk",
      "kind": "volume",
      "engine": "",
      "target_path": "/app/data",
      "source": "runtime_readonly",
      "status": "suggested",
      "detail": "Este app guarda dados em /app/data, mas o disco do app é somente-leitura. Posso criar um volume persistente em /app/data para os dados sobreviverem aos deploys. Criar agora?",
      "created_at": "2026-10-12T12:00:00Z"
    }
  ]
}
```

Os campos de cada sugestão:

| Campo | O que é |
|---|---|
| `id` | identificador da sugestão (use-o para descartar ou aceitar) |
| `service_id`, `service_name` | o serviço que precisa de persistência |
| `project_id` | o projeto do serviço |
| `kind` | `volume` (disco persistente) ou `database` (banco gerenciado) |
| `engine` | motor do banco (`sqlite`, `postgres`, `mysql`, `mongo`) ou vazio quando é volume |
| `target_path` | caminho do volume (ex.: `/app/data`); nulo quando é banco |
| `source` | o gatilho: `build_detect`, `runtime_readonly`, `runtime_connrefused` ou `unresolved_ref` |
| `status` | `suggested`, `dismissed`, `accepted` ou `fulfilled` |
| `detail` | mensagem em linguagem simples, pronta para a tela |
| `created_at` | quando a sugestão foi criada |

## Como um agent descarta uma sugestão

Para arquivar uma sugestão que não faz sentido, use o escopo `projects:write`:

```bash
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/suggestions/$SID/dismiss" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```

A sugestão passa a `dismissed` e não reaparece pelo mesmo sinal na mesma janela.

## Aceitar (criar o recurso) ainda vem a seguir

Aceitar uma sugestão — ou seja, **de fato criar** o volume ou o banco e ligá-lo ao serviço — está sendo finalizado e ainda não está disponível nesta versão da API. A rota prevista é:

```text
POST /v1/projects/{pid}/suggestions/{sid}/accept   (escopo de escrita)
```

O formato exato do corpo dessa chamada ainda não está definido e será documentado aqui quando a criação por aceite entrar no ar. Até lá, você pode criar o recurso sugerido pela rota direta: um [volume](/conectados/volumes/) para o caso SQLite embarcado, ou um [banco gerenciado](/bancos/postgres/) com a [referência de conexão](/bancos/conexao-e-referencias/) para o caso de driver externo.

## Paridade painel e API

Tudo o que o painel mostra e faz com sugestões, um agent faz pela API `/v1` — listar e descartar hoje, aceitar quando a criação por aceite entrar. Veja também o [Contrato de App Nebular](/agents/contrato-app/), que lista os erros de deploy que disparam estas sugestões, e o cookbook [Como corrigir cada erro de deploy](/agents/corrigir-deploy/) com o remédio de cada código. Quando a sugestão é um banco e o app usa SQLite embarcado, uma alternativa ao volume é [migrar para libSQL gerenciado](/agents/corrigir-deploy/#migrar-sqlite-local-para-gerenciado).

---

URL: https://docs.nebularws.com/dominios/dominio-proprio.md

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

```bash
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\"}"
```
```json
{"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:

```bash
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](/dominios/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](/operacao/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](/dominios/tls/) e [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/dominios/subdominio-gerado.md

# Subdomínio gerado

- Serviço com `visibility: "public"` é servido em `https://<slug>.<APPS_DOMAIN>` (o domínio de apps da plataforma; use sempre a URL que a API devolve, e a variável `PUBLIC_URL` dentro do grupo).
- Serviço com `visibility: "private"` **não recebe slug nem rota pública**: só é alcançado pelo `name` dentro do grupo ([Rede privada](/conectados/rede-privada/)).
- O `slug` é único na plataforma. Projetos antigos migrados mantêm o slug que já tinham, no serviço `web`.
- O HTTPS é emitido no primeiro acesso.

## Criar um serviço público com slug

```bash
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: sub-proj-$SUF" \
  -d "{\"name\": \"demo-sub-$SUF\"}" | jq -r '.id')

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-sub-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}"
```
```json
{"id": "01j9zktv26djn3k6dd2yraqsbt", "name": "web", "kind": "app", "visibility": "public"}
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `409 slug_taken` | Slug já em uso. Escolha outro e repita com uma `Idempotency-Key` nova. |
| `400 invalid_request` | `slug` malformado, ou `slug` informado num serviço `private` (privado não tem slug). |
| `404 not_found` | Projeto inexistente ou de outro time. |

Quer um nome próprio? Veja [Domínio próprio](/dominios/dominio-proprio/). Tabela completa: [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/dominios/tls.md

# TLS

- O HTTPS é **emitido automaticamente no primeiro acesso** a um domínio `active` (subdomínio gerado ou próprio). Você não envia certificado nem chave.
- O domínio precisa estar `active` ([Domínio próprio](/dominios/dominio-proprio/)): DNS apontando para a plataforma e TXT de posse publicado.
- Se o DNS está atrás de um proxy (Cloudflare laranja), a verificação falha com `proxied`: use DNS only.
- Bancos gerenciados usam um certificado de CA pública no seu `public_host`; veja [Conexão e referências](/bancos/conexao-e-referencias/).

Erro de certificado no primeiro acesso: confirme `status: active` e repita o acesso após alguns segundos. Persistindo, veja [Problemas comuns](/dominios/problemas-comuns/).

---

URL: https://docs.nebularws.com/dominios/redirecionamentos.md

# Redirecionamentos

Um domínio pode ser configurado para **redirecionar para outro domínio do mesmo projeto**. Regras:

- O alvo precisa ser outro domínio do mesmo projeto e **não pode ser ele próprio redirecionado** (sem cadeias, portanto sem ciclos).
- Um domínio que já é alvo de redirecionamento não pode virar origem de outro.
- Alvo inválido volta como erro de validação (`400`): corrija o alvo; não repita igual.

Ambos os domínios precisam ter DNS e TXT corretos ([Domínio próprio](/dominios/dominio-proprio/)). Redirecionamento de caminhos arbitrários ou regras por URL não são oferecidos.

Consulte a OpenAPI da v13 para o campo exato na criação/edição do domínio. Veja também [Problemas comuns](/dominios/problemas-comuns/).

---

URL: https://docs.nebularws.com/dominios/problemas-comuns.md

# Problemas comuns

Leia `status` e o motivo (campo `error`) do domínio com `GET /v1/projects/{p}/services/{s}/domains/{d}`.

| Motivo | O que significa | O que fazer |
|---|---|---|
| `no_records` | o nome não resolve | Crie os registros DNS da resposta (CNAME ou A/AAAA, mais o TXT) e espere propagar. |
| `wrong_target` | resolve, mas não para a plataforma | Ajuste o CNAME/A para os valores da resposta. |
| `proxied` | os registros estão atrás do proxy da Cloudflare | Mude para DNS only (nuvem cinza). |
| `txt_missing` | DNS correto, mas falta provar a posse | Publique `_nebular-verify.<dominio>` TXT `nebular-verify=<token>`. |
| `conflict` | ativo em outro projeto | Publique o TXT de posse: com a prova o domínio é transferido para este projeto. |
| `dns_error` | falha momentânea ao consultar DNS | Nada: a verificação repete sozinha. Espere com backoff. |

Estado `error` com `error = misconfigured`: o DNS que funcionava deixou de apontar para a plataforma; restaure os registros e o domínio reativa sozinho.

Verificação manual imediata é limitada por taxa por domínio; prefira esperar com backoff (2 s, dobrando até 30 s) a repetir em laço fechado. `429` = espere `Retry-After`.

Veja [Domínio próprio](/dominios/dominio-proprio/) e [Erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/cdn/visao-geral.md

# CDN e galerias: visão geral

Uma **galeria** é uma pasta de arquivos do seu time servida pela CDN da Nebular (`https://media.nebularcdn.com/...`).
Com um token de API você sobe imagens, fontes, PDFs e outros arquivos, cada novo envio com o mesmo nome vira uma
**versão**, e recebe duas URLs prontas para usar em sites e apps:

- **URL imutável** (`url`): inclui o hash do conteúdo; nunca muda de conteúdo; cache de 1 ano. Use quando o
  arquivo for referenciado por algo que não deve mudar sozinho.
- **URL alias** (`alias_url`): sempre aponta para a versão atual; cache curto (60 s). Use em sites: trocar a imagem
  não exige trocar a URL.

Tudo que sobe é varrido (antivírus, regras de webshell/phishing, reputação por hash e uma varredura própria de SVG)
**antes** de ser publicado. Veja [Classes de arquivo e varredura](/cdn/classes-de-arquivo-e-varredura/).

Próximos passos: [Galerias e arquivos](/cdn/galerias/), [Transformar imagens](/cdn/transformar-imagens/), [Cache e purge](/cdn/cache-e-purge/).

---

URL: https://docs.nebularws.com/cdn/galerias.md

# Galerias e arquivos

## Galerias

### Listar galerias (`assets:read`)

Parâmetros: `project` (filtra por projeto) e `cursor` (veja a receita de paginação, a receita "Listar com cursor" abaixo).

```bash
curl -sS "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{
  "items": [
    {
      "id": "gal_01J9ZK5Q",
      "key": "marcas-k7p2",
      "name": "Marcas",
      "bucket": {"id": "bkt_01J9ZG00", "label": "media", "kind": "shared", "host": "media.nebularcdn.com"},
      "project": null,
      "assets_count": 12,
      "bytes": 4823910,
      "created_at": "2026-10-09T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

`key` é a identificação pública e **imutável** da galeria (nomes podem mudar): é ela que vai nas rotas e nas URLs.

### Criar galeria (`galleries:manage`)

`name` (1 a 80 caracteres) é obrigatório; `project_id` (opcional) apenas organiza a galeria sob um projeto.

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marcas"}'
```
```json
{
  "id": "gal_01J9ZK5Q",
  "key": "marcas-k7p2",
  "name": "Marcas",
  "bucket": {"id": "bkt_01J9ZG00", "label": "media", "kind": "shared", "host": "media.nebularcdn.com"},
  "project": null,
  "assets_count": 0,
  "bytes": 0,
  "created_at": "2026-10-09T14:03:11Z"
}
```

Guarde o `key` retornado (nos exemplos: `$GALLERY`). Cada chamada cria uma galeria nova, então não repita sem necessidade.

## Arquivos

### Enviar ou versionar (`assets:write`)

Corpo `multipart/form-data` com `file` (obrigatório) e `name` (opcional; padrão: o nome do arquivo enviado
normalizado). Se o nome já existir, cria uma **nova versão** e o alias passa a apontar para ela. Enviar o mesmo
conteúdo (mesmo SHA-256) para o mesmo nome não cria versão nova.

Respostas: **201** (limpo e já publicado), **202** (`pending`: ainda não publicado, veja [Uploads pending](#uploads-pending-202-como-esperar)) ou um erro ([Erros](/erros/tabela/)).

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: logo-acme-2026-10-09" \
  -F "file=@logo.png" \
  -F "name=logos/acme.png"
```
```json
{
  "id": "ast_01J9ZK8W",
  "name": "logos/acme.png",
  "gallery_key": "marcas-k7p2",
  "current": {
    "id": "ver_01J9ZK8X",
    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "bytes": 48213,
    "content_type": "image/png",
    "class": "image",
    "width": 1200,
    "height": 630,
    "variants": ["320", "640", "1280"],
    "scan": {"status": "clean", "reason": null, "engine": "clamav", "scanned_at": "2026-10-09T14:05:02Z"},
    "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
    "uploaded_by": {"kind": "token", "name": "agente-deploy"},
    "created_at": "2026-10-09T14:05:01Z"
  },
  "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
  "versions_count": 1,
  "created_at": "2026-10-09T14:05:01Z"
}
```

Use sempre a `url`/`alias_url` devolvidas pela API, sem montá-las à mão (o domínio de classes de download pode mudar).
`url` e `alias_url` são `null` enquanto o arquivo não estiver `clean`.

### Idempotência (`Idempotency-Key`)

Envie `Idempotency-Key` (até 255 caracteres; um UUID ou algo derivado do conteúdo) em todo upload automatizado.
Mesma chave com o **mesmo corpo** devolve a mesma resposta, então repetir após timeout ou erro de rede é seguro e não cria
versões duplicadas. Mesma chave com **corpo diferente** devolve `409 idempotency_conflict`: gere uma chave nova.

```bash
# repetir a mesma chave com o mesmo arquivo devolve a mesma resposta
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: logo-acme-2026-10-09" \
  -F "file=@logo.png" \
  -F "name=logos/acme.png"
```
```json
{"id": "ast_01J9ZK8W", "name": "logos/acme.png", "versions_count": 1, "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png"}
```

Mesma chave, arquivo diferente:

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: logo-acme-2026-10-09" \
  -F "file=@banner.png" \
  -F "name=logos/acme.png"
```
```json
{"error": "idempotency_conflict", "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."}
```

### Listar arquivos (`assets:read`)

Parâmetros: `prefix` (só nomes que começam com ele) e `cursor`.

```bash
curl -sS -G "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  --data-urlencode "prefix=logos/" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{
  "items": [
    {
      "id": "ast_01J9ZK8W",
      "name": "logos/acme.png",
      "gallery_key": "marcas-k7p2",
      "current": {
        "id": "ver_01J9ZK8X",
        "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "bytes": 48213,
        "content_type": "image/png",
        "class": "image",
        "width": 1200,
        "height": 630,
        "variants": ["320", "640", "1280"],
        "scan": {"status": "clean", "reason": null, "engine": "clamav", "scanned_at": "2026-10-09T14:05:02Z"},
        "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
        "uploaded_by": {"kind": "token", "name": "agente-deploy"},
        "created_at": "2026-10-09T14:05:01Z"
      },
      "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
      "versions_count": 1,
      "created_at": "2026-10-09T14:05:01Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Detalhe, versões e status de varredura (`assets:read`)

O nome vai na rota; use `%2F` no lugar de cada `/` (a barra literal também é aceita).

```bash
curl -sS "$NEBULAR_API/v1/galleries/$GALLERY/assets/logos%2Facme.png" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{
  "asset": {
    "id": "ast_01J9ZK8W",
    "name": "logos/acme.png",
    "gallery_key": "marcas-k7p2",
    "current": {
      "id": "ver_01J9ZK8X",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "bytes": 48213,
      "content_type": "image/png",
      "class": "image",
      "width": 1200,
      "height": 630,
      "variants": ["320", "640", "1280"],
      "scan": {"status": "clean", "reason": null, "engine": "clamav", "scanned_at": "2026-10-09T14:05:02Z"},
      "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
      "uploaded_by": {"kind": "token", "name": "agente-deploy"},
      "created_at": "2026-10-09T14:05:01Z"
    },
    "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
    "versions_count": 1,
    "created_at": "2026-10-09T14:05:01Z"
  },
  "versions": [
    {
      "id": "ver_01J9ZK8X",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "bytes": 48213,
      "content_type": "image/png",
      "class": "image",
      "width": 1200,
      "height": 630,
      "variants": ["320", "640", "1280"],
      "scan": {"status": "clean", "reason": null, "engine": "clamav", "scanned_at": "2026-10-09T14:05:02Z"},
      "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
      "uploaded_by": {"kind": "token", "name": "agente-deploy"},
      "created_at": "2026-10-09T14:05:01Z"
    }
  ]
}
```

### Excluir (`assets:write`)

Exclui o arquivo e purga o cache da CDN (a URL passa a dar 404). O backup retém os bytes por 30 dias.
Resposta: `204` sem corpo.

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -F "file=@hero.png" -F "name=temp/hero.png" -o /dev/null
curl -sS -X DELETE "$NEBULAR_API/v1/galleries/$GALLERY/assets/temp%2Fhero.png" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -w 'HTTP %{http_code}\n'
```

Depois disso o `GET` do mesmo nome devolve `404 not_found`.

## Uploads pending (202): como esperar

Se o scanner estiver ocupado ou fora do ar, o upload devolve **202** com `scan.status = "pending"`, `url` e `alias_url`
`null`: o arquivo foi recebido mas **não está publicado**. **Não reenvie.** Consulte o detalhe do arquivo com
backoff (comece em 2 s, dobre a cada tentativa até 30 s) até `scan.status` deixar de ser `pending`:
`clean` (publicado, `url`/`alias_url` preenchidos) ou `rejected` (recusado; o campo `scan.reason` diz o motivo).

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -F "file=@slow.png" -F "name=site/lento.png"
```
```json
{
  "id": "ast_01J9ZK8W",
  "name": "site/lento.png",
  "gallery_key": "marcas-k7p2",
  "current": {
    "id": "ver_01J9ZK8X",
    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "bytes": 48213,
    "content_type": "application/octet-stream",
    "class": "binary",
    "width": null,
    "height": null,
    "variants": [],
    "scan": {"status": "pending", "reason": null, "engine": null, "scanned_at": null},
    "url": null,
    "uploaded_by": {"kind": "token", "name": "agente-deploy"},
    "created_at": "2026-10-09T14:05:01Z"
  },
  "alias_url": null,
  "versions_count": 1,
  "created_at": "2026-10-09T14:05:01Z"
}
```

Enquanto `pending`, `content_type`/`class` são provisórios (`application/octet-stream`/`binary`) e `width`/`height` são `null`;
valem os valores do `GET` depois que o status virar `clean`.

Polling com backoff (no máximo 8 tentativas):

```bash
delay=2
for attempt in 1 2 3 4 5 6 7 8; do
  status=$(curl -sS "$NEBULAR_API/v1/galleries/$GALLERY/assets/site%2Flento.png" \
    -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.current.scan.status')
  echo "tentativa $attempt: $status"
  [ "$status" = "pending" ] || break
  sleep "$delay"
  delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$status" = "clean" ]   # sai com erro se foi recusado ou se ainda está pendente
```

## Receitas

### (a) Subir e usar no Next com `next/image`

1. Suba a imagem e guarde a `alias_url`:

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: hero-$(cksum < hero.png | tr ' ' '-')" \
  -F "file=@hero.png" -F "name=site/hero.png" | jq -r '.alias_url'
```

2. Um loader de `next/image` que acrescenta `?w=&q=` (larguras do `next/image` já estão na lista permitida):

```ts
// lib/nebularLoader.ts
import type { ImageLoaderProps } from "next/image";

export default function nebularLoader({ src, width, quality }: ImageLoaderProps): string {
  const url = new URL(src);
  url.searchParams.set("w", String(width));
  url.searchParams.set("q", String(quality ?? 75));
  return url.toString();
}
```

3. Libere o host e use o loader (o `src` é a `alias_url` sem parâmetros):

```ts
// next.config.ts
import type { NextConfig } from "next";

const config: NextConfig = {
  images: {
    loader: "custom",
    loaderFile: "./lib/nebularLoader.ts",
  },
};
export default config;
```

```tsx
import Image from "next/image";

export function Hero() {
  return (
    <Image
      src="https://media.nebularcdn.com/marcas-k7p2/site/hero.png"
      alt="Banner principal"
      width={1200}
      height={630}
      sizes="100vw"
    />
  );
}
```

Como o alias sempre aponta para a versão atual, trocar a imagem (receita c) atualiza o site sem novo deploy.

### (b) Subir em lote com laço shell (429, Retry-After e idempotência)

A `Idempotency-Key` derivada do conteúdo torna o laço seguro de repetir inteiro: o que já foi enviado não gera versão nova.
Erros permanentes (4xx exceto 429) não são repetidos; 429 e 503 esperam `Retry-After`.

```bash
fail=0
for f in imagens/*.png; do
  name="lote/$(basename "$f")"
  key="lote-$name-$(cksum < "$f" | tr ' ' '-')"
  for try in 1 2 3 4 5; do
    code=$(curl -sS -o resp.json -D hdr.txt -w '%{http_code}' \
      -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
      -H "Authorization: Bearer $NEBULAR_TOKEN" \
      -H "Idempotency-Key: $key" \
      -F "file=@$f" -F "name=$name")
    case "$code" in
      201|202) echo "$name -> $code"; break ;;
      429|503)
        wait=$(awk -F': ' 'tolower($1)=="retry-after"{print $2+0}' hdr.txt)
        echo "$name -> $code, aguardando ${wait:-5}s (tentativa $try)" >&2
        sleep "${wait:-5}" ;;
      *) echo "$name FALHOU ($code): $(cat resp.json)" >&2; fail=1; break ;;
    esac
  done
done
[ "$fail" = 0 ]
```

Arquivos que voltarem `202` ainda precisam do polling da [Uploads pending](#uploads-pending-202-como-esperar) antes de a URL existir.

### (c) Trocar uma imagem mantendo a `alias_url`

Envie o novo arquivo **com o mesmo `name`**: nasce uma nova versão e o alias passa a servir a nova imagem; a `url`
imutável antiga continua válida (e imutável). Não precisa mudar nada em quem usa a `alias_url`.

```bash
alias_antes=$(curl -sS "$NEBULAR_API/v1/galleries/$GALLERY/assets/site%2Fhero.png" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.alias_url')

curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -F "file=@logo-v2.png" -F "name=site/hero.png" > nova.json

jq -r '"versões: \(.versions_count)"' nova.json
test "$(jq -r '.alias_url' nova.json)" = "$alias_antes"   # a alias_url não mudou
test "$(jq -r '.versions_count' nova.json)" = "2"
```

Se a `alias_url` ainda mostrar a imagem antiga por instantes, é o cache de 60 s do alias; a `url` imutável da nova
versão já serve o novo conteúdo.

### (d) Listar com cursor (`next_cursor` / `has_more`)

Siga `next_cursor` enquanto `has_more` for `true`. O cursor é opaco: não monte nem altere.

```bash
cursor=""
while :; do
  url="$NEBULAR_API/v1/galleries/$GALLERY/assets"
  [ -n "$cursor" ] && url="$url?cursor=$cursor"
  page=$(curl -sS "$url" -H "Authorization: Bearer $NEBULAR_TOKEN")
  echo "$page" | jq -r '.items[] | "\(.name)\t\(.alias_url)"'
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.next_cursor')
done
```

O mesmo vale para `GET /v1/galleries`.

---

URL: https://docs.nebularws.com/cdn/transformar-imagens.md

# Transformar imagens

**Imagens** (`class: image`) aceitam `?w=<largura>&q=<qualidade>` em ambas as URLs; o formato (AVIF/WebP/original) é
negociado pelo cabeçalho `Accept` (`Vary: Accept`):

- `w` só aceita as larguras `16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840`
  (as mesmas do `next/image`); outro valor ⇒ `400` da CDN. Nunca amplia além do original.
- `q` vai de 30 a 95 (padrão 75 quando só `w` é enviado) e **exige** `w`.
- `w` e `q` valem **só para imagens**: em qualquer outra classe são ignorados. **Parâmetros desconhecidos** (por exemplo
  `?v=123` como cache-buster) também são ignorados e não geram variantes novas.

Receita com `next/image`: veja [Galerias e arquivos](/cdn/galerias/#a-subir-e-usar-no-next-com-nextimage).

---

URL: https://docs.nebularws.com/cdn/classes-de-arquivo-e-varredura.md

# Classes de arquivo e varredura

## Classes de arquivo

A classe vem do **conteúdo** (magic bytes), nunca da extensão nem do `Content-Type` enviado.

| Classe | Exemplos | Servido como |
|---|---|---|
| `image` | png, jpeg, webp, gif, avif | inline, transformável (`?w=`, `?q=`) |
| `svg` | svg | inline **só se passar na varredura de SVG**, sempre com CSP restritiva (`default-src 'none'; sandbox`) |
| `font` | woff2, woff, ttf, otf | inline, CORS `*` |
| `media` | mp4, webm, mp3, ogg | inline, com `Accept-Ranges` |
| `document` | pdf, txt, csv, json | **download** (`Content-Disposition: attachment`); texto sempre `text/plain` |
| `markup` | html, htm, xhtml, xml | **nunca renderiza**: download + `text/plain` + CSP `sandbox` |
| `archive` | zip, tar.gz | download; cifrado ou impossível de varrer é recusado |
| `binary` | exe, msi, dmg, apk, deb, appimage, desconhecido | download, `application/octet-stream` |

As URLs são sem cookies, com `X-Content-Type-Options: nosniff`; CORS `*` só para `image` e `font`. Não use um arquivo de
download (`document`, `markup`, `archive`, `binary`) como `<script>`/`<iframe>`: ele não renderiza por desenho.

## Varredura, quarentena e 451

- Todo arquivo entra em **quarentena** e só é publicado depois de `clean`: antivírus, regras YARA, reputação por
  hash (só o hash sai da nossa infraestrutura, nunca o conteúdo), decodificação de imagens em sandbox e varredura
  específica de SVG. **Nada é publicado antes de `clean`.**
- Detectado ⇒ recusado (`422`), com auditoria. A amostra não é guardada.
- Se o scanner estiver fora do ar, o upload fica `pending` (202) e **não** é publicado (fail-closed).
- **Nova varredura diária** de tudo que está publicado, com as assinaturas do dia. Um arquivo que passou ontem pode
  ser detectado hoje: ele muda para `quarantined`, **sai do ar** (a CDN passa a responder `451`), o cache é purgado e o
  time é avisado. Em sistemas que dependem de uma URL, trate `451` como "indisponível por motivo de segurança": não
  insista, avise uma pessoa. Consulte `scan.status` / `scan.reason` no detalhe do arquivo.

## Por que meu SVG foi recusado e como reexportar

O SVG é um arquivo ativo (pode conter script), então só publicamos **SVG estático**, sem limpar nem alterar nada: o
que vai ao ar é o arquivo exatamente como você enviou. O `422 svg_unsafe` traz `reasons[]` com códigos do scanner;
a orientação é a mesma que o painel mostra:

| Se o motivo for… | O que significa | Como resolver |
|---|---|---|
| script, eventos ou links externos (`script_element`, `event_handler_attr`, `dangerous_scheme`, `external_or_unsafe_url`, `xml_base`, `form_element`, `embed_element`, `media_element`, `link_meta_element`, …) | O SVG contém script, atributos de evento (`onclick`, `onload`…) ou referências a URLs externas. | Remova scripts/`onclick` e referências a URLs externas. Só aceitamos SVG estático. |
| CSS externo (`style_type`, `css_*`) | O CSS do SVG referencia recursos externos ou ativos (`url()` externo, `@import`, `expression`). | Use estilos sem `url()` externo. |
| imagem embutida (`data_uri_not_allowed`, `data_uri_magic_mismatch`) | Imagem embutida não permitida. | Só PNG/JPEG/GIF/WebP em base64 são aceitos como imagem embutida. |
| Illustrator / HTML embutido (`foreign_namespace_element`, `html_element`, `ns_forbidden`, `ns_prefix_spoof`, `metadata_ns_outside_metadata`) | O SVG foi salvo com **"Preservar recursos de edição do Illustrator"** ou contém HTML embutido. | No Illustrator: **Arquivo → Exportar → Exportar para telas (SVG)**, ou **Salvar como SVG** desmarcando "Preservar recursos de edição". |
| DOCTYPE/ENTITY antigo (`doctype_entity`, `doctype_internal_subset`, `doctype_not_allowed`, `doctype_too_long`, `directive_not_allowed`, `processing_instruction`) | O SVG tem um cabeçalho `<!DOCTYPE …>` / `<!ENTITY …>` antigo. | Reexporte como **SVG 1.1** (Illustrator: Exportar para telas; Inkscape: **Salvar como → SVG otimizado**) ou remova o bloco `<!DOCTYPE …>`. |
| tamanho (`too_large`, `too_deep`, `too_many_elements`, `too_many_attrs`, `name_too_long`, `css_too_large`) | O SVG é grande ou complexo demais. | Simplifique/otimize (ex.: SVGO) e envie de novo. |
| formato (`xml_malformed`, `no_root`, `not_svg_root`, `multiple_roots`, `text_outside_root`, `duplicate_attribute`, `odd_attr_name`, `odd_element_name`, `deprecated_element`, `attr_namespace`, `style_element`) | O arquivo não é um SVG válido ou bem formado. | Reexporte do editor. |

Quando houver vários motivos, resolva primeiro os de segurança (script/eventos/links, CSS, imagem embutida), depois os
de exportação (Illustrator, DOCTYPE), depois tamanho e formato. Códigos que não estão na tabela: reexporte como
SVG 1.1 estático e, se persistir, denuncie o problema ao time com o `reasons` recebido.

---

URL: https://docs.nebularws.com/cdn/cache-e-purge.md

# Cache e purge

**Imutável** `https://media.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`: `Cache-Control: public,
max-age=31536000, immutable`. **Alias** `https://media.nebularcdn.com/<gallery_key>/<name>`: `public, max-age=60,
stale-while-revalidate=86400`; nova versão ou exclusão invalida o cache.

Nova versão, exclusão ou quarentena purgam o cache. Não há rota pública de purge manual: troque o arquivo (mesmo `name`) ou use a URL imutável.

---

URL: https://docs.nebularws.com/operacao/rollback.md

# Rollback

Escopo: `deploy`. O rollback é **por serviço**: volta ao deployment anterior do serviço, **com as variáveis resolvidas daquela versão** (não as atuais).

## 1. Escolher o deploy de destino

Liste os deploys do serviço e pegue o `id` de um que esteja `ready` e seja anterior ao problema.

```bash
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" \
  -H "Idempotency-Key: rb-proj-$SUF" -d "{\"name\": \"rb-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: rb-svc-$SUF" \
  -d '{"name": "app", "kind": "app", "visibility": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H"
```
```json
{"items": [], "next_cursor": null, "has_more": false}
```

Em um serviço com histórico, extraia os pares com `jq -r '.items[] | "\(.id)\t\(.status)"'`.

## 2. Reverter

```bash
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\": \"rb2-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

# o destino do rollback precisa ter terminado com sucesso (ready)
delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/rollback" \
  -H "$H" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rollback-$D" -d '{}'
```
```json
{"id": "01j9zkbssrj776q2jrwy8cf13v", "status": "queued"}
```

Acompanhe o novo deploy com [polling](/operacao/deploys-e-status/) até `ready`.

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `403 forbidden` | Falta o escopo `deploy`. |
| `404 not_found` | Deploy, serviço ou projeto inexistente ou fora do seu acesso. |
| `409 nothing_to_rollback` | O deploy de destino não terminou com sucesso (`ready`). Escolha outro ou espere. |
| `409 deploy_in_progress` | Há um deploy em andamento; espere terminar e tente de novo. |
| deploy do rollback `failed` | Leia o [log de build](/operacao/logs/); se o problema era dado e não código, o rollback não o desfaz (migrations: veja [Migrações](/bancos/migracoes/)). |

---

URL: https://docs.nebularws.com/operacao/logs.md

# Logs

Escopo: `logs:read`. Segredos (valores sensíveis das variáveis) são mascarados nos logs.

## Log de build de um deploy

`GET /v1/projects/{p}/services/{s}/deployments/{d}/logs?cursor=`. Lista paginada por cursor: siga `next_cursor` enquanto `has_more` for `true`. Use quando o deploy terminar em `failed`.

```bash
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\": \"lg1-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D/logs" \
  -H "$H"
```
```json
{"text": "[build] fetching source\n", "next_cursor": "Mw", "done": false}
```

Para o próximo trecho: `...logs?cursor=$NEXT_CURSOR`, sem alterar o cursor (é opaco).

## Log de runtime de um serviço

`GET /v1/projects/{p}/services/{s}/logs?since=&cursor=`. `since` limita ao que veio depois de um instante (RFC 3339 em UTC).

```bash
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\": \"lg2-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)

curl -sS -G "$NEBULAR_API/v1/projects/$P/services/$S/logs" \
  --data-urlencode "since=2026-10-10T12:00:00Z" \
  -H "$H"
```
```json
{"text": "boot service=web\n", "next_cursor": "Mg", "done": false}
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `403 forbidden` | Falta `logs:read`. |
| `404 not_found` | Serviço ou deploy inexistente ou fora do seu acesso. |
| `400 invalid_request` | `since` ou `cursor` malformado. |
| `429` | Espere `Retry-After`; não faça polling mais rápido que 2 s. |

Diagnóstico: [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/).

---

URL: https://docs.nebularws.com/operacao/deploys-e-status.md

# Deploys e status

Escopos: `deploy` (disparar), `projects:read` (consultar).

## Estados

| Estado | Significado | O agent deve |
|---|---|---|
| `queued` | na fila | esperar |
| `building` | construindo | esperar |
| `deploying` | subindo o container | esperar |
| `ready` | no ar | terminar com sucesso |
| `failed` | build ou subida falhou | ler o [log de build](/operacao/logs/) e corrigir; não repetir igual |
| `blocked` | um serviço do qual este depende falhou no deploy de grupo | corrigir o dependente primeiro |
| `canceled` | cancelado | decidir se dispara de novo |
| `superseded` | um deploy mais novo tomou o lugar | acompanhar o mais novo |

## Disparar

- Serviço: `POST /v1/projects/{p}/services/{s}/deployments` (git ref, imagem ou upload multipart). Veja [Primeiro deploy](/comecar/primeiro-deploy/).
- Grupo: `POST /v1/projects/{p}/deploy` (corpo `{}` com `Content-Type: application/json`, ou sem corpo). Ordem topológica das referências entre serviços: quem é referenciado sobe antes. Se o build de um serviço falhar, os dependentes ficam `blocked`; os serviços já ativos permanecem. Serviço `upload` que já recebeu arquivo é reimplantado com o último arquivo; sem nenhum arquivo (sem fonte), o item vem `skipped` com `reason` e o grupo segue ([Front, back e banco](/conectados/front-back-db/#5-deploy-do-grupo)).

## Consultar e listar

```bash
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" \
  -H "Idempotency-Key: dep-proj-$SUF" -d "{\"name\": \"dep-$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": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H"
```
```json
{"items": [], "next_cursor": null, "has_more": false}
```

A lista usa cursor (`next_cursor`, `has_more`): siga enquanto `has_more` for `true`.

## Polling com backoff

Não há webhooks neste ciclo. Consulte `GET .../deployments/{d}`: comece em 2 s, dobre a cada tentativa até 30 s, no máximo cerca de 10 minutos (40 tentativas). Pare em qualquer estado terminal.

```bash
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\": \"dep2-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

delay=2
for i in $(seq 1 40); do
  st=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" -H "$H" | jq -r .status)
  echo "tentativa $i: $st"
  case "$st" in
    ready) break ;;
    failed|blocked|canceled|superseded) echo "deploy terminou em $st" >&2; exit 1 ;;
  esac
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$st" = ready ]
```

**Deploy de grupo**: faça polling no grupo, não serviço a serviço: `GET /v1/projects/{p}/group-deployments/{g}` (`g` é o `id` devolvido pelo `POST .../deploy`). O `status` do grupo é `running` até terminar e então `ready`, `failed`, `canceled` ou `superseded`; cada item tem seu `status` (inclui `blocked` e `skipped`). Mesmo backoff.

Em `429`, espere o `Retry-After` antes da próxima consulta ([Rate limit e retry](/erros/rate-limit-e-retry/)).

## Auto-deploy por git

Com `auto_deploy: true` e `source.type = "git"`, o push no branch dispara deploy. O webhook encontra **todos** os serviços ligados àquele repositório e branch. Com `watch_paths` (ex.: `["apps/api/**"]`) só os serviços afetados são reimplantados; se vários serviços do mesmo projeto forem afetados, vira um deploy de grupo. Veja [Monorepo](/guia/monorepo/).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `404 not_found` | Deploy, serviço ou projeto inexistente ou fora do seu acesso. |
| deploy `failed` | Leia o [log de build](/operacao/logs/). Se a imagem exige root, o container não sobe: use uma imagem que rode como não-root. |
| deploy `blocked` | Corrija o serviço dependente que falhou e dispare o grupo de novo. |
| `unresolved_reference` / `reference_cycle` | [Variáveis e referências](/conectados/variaveis-e-referencias/). |
| `409 deploy_in_progress` | Já há um deploy em andamento para o recurso; acompanhe-o. |

---

URL: https://docs.nebularws.com/operacao/limites-e-cotas.md

# Limites e cotas

- **25 MB por arquivo**; imagens também limitadas a **40 megapixels**.
- **Cota por time**: 5 GB e 10 000 arquivos no bucket compartilhado.
- **Nomes de arquivo** (`name`): até 4 segmentos separados por `/` (3 barras), cada um em `[a-z0-9._-]`, até 200
  caracteres, sem `..`, sem segmento começando com `.`, e o **primeiro segmento não pode ter exatamente 12
  caracteres hexadecimais** (colidiria com o hash da URL imutável). Únicos dentro da galeria. Nome inválido ⇒ `400 invalid_request`.
- **Rate-limit** por token e por IP. Ao receber `429`, espere o número de segundos do cabeçalho `Retry-After`.

## Limites de deploy, serviços e recursos

Os valores exatos do seu plano e do seu time estão em `GET /v1/limits` (escopo: qualquer token válido); o que o token pode fazer está em `GET /v1/me`.

```bash
curl -sS "$NEBULAR_API/v1/limits" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"plan": "hobby", "services": {"used": 1, "max": 10}, "memory_mb": {"used": 512, "max": 4096}, "volumes_gb": {"used": 0, "max": 20}, "databases": {"used": 0, "max": 3}, "deploys_per_hour": {"used": 0, "max": 30}}
```

Cada dimensão traz `used` e `max`. Passar de `max` em serviços, memória, volume ou bancos responde `quota_exceeded` (`422` ao criar banco); `deploys_per_hour` limita o disparo de deploys por time (janela deslizante de 1 h, somando todos os projetos): ao atingir, deploy, rollback e deploy de grupo respondem `429 rate_limited` com `Retry-After` (segundos até abrir vaga). Aguarde; não é erro de cota permanente. O número máximo de projetos por time (`project_quota_exceeded`, `409`) é conferido na criação do projeto.

Regras fixas do modelo:

- **Nome de serviço**: `^[a-z][a-z0-9-]{0,30}$`, único no projeto.
- **Recursos por serviço**: `memory_mb` padrão 512 e `cpus` padrão 0.5, até o máximo do plano ([Escala e recursos](/operacao/escala-e-recursos/)).
- **Volume**: 1 por serviço, de 1 a 50 GB ([Volumes](/conectados/volumes/)).
- **Variáveis**: valor expandido até 64 KiB e ambiente resolvido até 256 KiB (`value_too_large`); referências aninhadas até 16 níveis.
- **Banco**: cota em MB por instância; acima do limite o banco fica somente leitura ([Bancos](/bancos/postgres/)).
- Estourar uma cota responde `quota_exceeded`; excesso de requisições, `429` com `Retry-After`.

---

URL: https://docs.nebularws.com/operacao/escala-e-recursos.md

# Escala e recursos

Escopo: `projects:write` (alterar) e `deploy` (aplicar).

## O que se configura

| Campo (dentro de `resources`) | Padrão | Observação |
|---|---|---|
| `resources.memory_mb` | 512 | máximo definido pelo plano do time (`GET /v1/limits`) |
| `resources.cpus` | 0.5 | |

`memory_mb` e `cpus` ficam **dentro de `"resources"`**, nunca soltos no topo do corpo. Enviar `{"memory_mb": 1024}` é recusado com `400 invalid_request` (a mensagem diz o formato certo); a API não ignora campo desconhecido em silêncio.

O serviço roda com limite de memória, sem swap extra, de CPU e de processos. Estourar a memória encerra o processo do container. Réplicas não fazem parte deste ciclo; para escrever o app já preparado para elas, veja [App pronto para a Nebular e para escalar](/operacao/app-pronto-para-escalar/).

## Alterar

```bash
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" \
  -H "Idempotency-Key: esc-proj-$SUF" -d "{\"name\": \"esc-$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": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/$S" -H "$H" \
  -H "Content-Type: application/json" -d '{"resources": {"memory_mb": 1024, "cpus": 1}}'
```
```json
{"id": "01j9zkwf4q15w38y0taf680jvv", "name": "web", "kind": "app", "visibility": "private", "port": 3000}
```

A mudança vale a partir do próximo deploy do serviço: dispare um ([Deploys e status](/operacao/deploys-e-status/)).

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | Valor fora do máximo do plano, campo desconhecido (ex.: `memory_mb` fora de `resources`) ou valor inválido: consulte `GET /v1/limits`, reduza e confira o formato `{"resources": {...}}`. |
| `403 forbidden` | Falta `projects:write`. |
| `404 not_found` | Projeto ou serviço inexistente ou fora do seu acesso. |
| `quota_exceeded` | Limite do time atingido: veja [Limites e cotas](/operacao/limites-e-cotas/). |

---

URL: https://docs.nebularws.com/operacao/app-pronto-para-escalar.md

# App pronto para a Nebular e para escalar

Para a versão curta e normativa, que serve de briefing a um agent, veja o [Contrato de App Nebular](/agents/contrato-app/).

Esta página é para quem escreve o app (pessoa ou agent). Ela junta o que a plataforma **faz hoje** com um conjunto de hábitos que evitam reescrever o app quando houver mais de uma cópia dele rodando.

## O que existe hoje e o que não existe

| Tema | Hoje | Futuro |
|---|---|---|
| Cópias do serviço | **Uma** por serviço. Não há campo de réplicas na API. | Réplicas **não existem** e **não há data prometida**. Esta página só prepara o app para o dia em que existirem. |
| Deploy | Blue/green: o container novo passa no health check antes de receber tráfego; o antigo some após uma drenagem. Se o novo falha, o anterior continua no ar. | Sem mudança no app. |
| Recursos | `resources.memory_mb` e `resources.cpus` por serviço ([Escala e recursos](/operacao/escala-e-recursos/)). Serviços novos nascem com 512 MB e 0.5 CPU; quando o serviço não define nada, o runtime usa 1 GiB e 1 vCPU. Declare `resources` explícito e não dependa do padrão. | — |
| Escalar | Só **vertical** (mais memória/CPU, até o máximo do plano). | Horizontal, se e quando existir. |
| Disco | Raiz somente leitura. Graváveis: `/tmp` (tmpfs, 64 MB, sem exec) e o [volume](/conectados/volumes/) do serviço (1 por serviço, 1 a 50 GB). | Volume continua pertencendo a um serviço. |

**Escreva hoje como se houvesse N cópias**: custa pouco agora. Cron e worker gerenciados também não existem.

## Princípios (12-factor aplicados à Nebular)

### 1. Processo sem estado

Cada container é **efêmero**: roda sob gVisor (`runsc`), é recriado a cada deploy e pode ser reiniciado (limite de memória estourado, queda do app). Nada que esteja só na memória ou no disco do container sobrevive a isso.

Não guarde em variável global, arquivo local ou memória do processo:

- **sessão de login** (use token assinado, ou tabela de sessões no banco);
- **cache que precisa ser coerente** entre requisições (um cache só de otimização, que pode estar vazio a qualquer momento, é aceitável);
- **uploads** (veja a seção de réplicas);
- **contadores, filas e locks** (use o banco).

Teste simples: reinicie o app no meio de um fluxo. Se o usuário perde algo, havia estado local.

### 2. Config por variável de ambiente

Toda configuração vem do ambiente: URL do banco, chaves, URLs de outros serviços. Nada de arquivo de config gravado no build com valores de produção, e nada de segredo no repositório.

- Variáveis do serviço e do projeto: [Variáveis e referências](/conectados/variaveis-e-referencias/). Para apontar para outro serviço use `${{api.PRIVATE_URL}}`; para um valor comum a vários serviços, `${{shared.NOME}}`.
- **Banco gerenciado**: o app lê `DATABASE_URL` (via referência `${{db.…}}`, veja [Conexão e referências](/bancos/conexao-e-referencias/)). Não monte a URL na mão nem use outro banco.
- Mudar variável só vale no **próximo deploy**.
- Segredo nunca em `NEXT_PUBLIC_*` ou equivalente de bundle de browser.

### 3. Escute em `0.0.0.0:$PORT`

O app lê a variável `PORT` e escuta em `0.0.0.0`, não em `localhost`/`127.0.0.1`. A porta declarada no serviço (`port`) sempre vence e é a que o container recebe em `PORT`. Portas abaixo de 1024 não estão disponíveis (Go: `"0.0.0.0:" + os.Getenv("PORT")`; Node: `server.listen(PORT, "0.0.0.0")`).

### 4. Health check barato

Sem `healthcheck_path`, qualquer resposta HTTP em `/` basta. Com ele, o container novo só recebe tráfego quando `GET <healthcheck_path>` responde **2xx ou 3xx** (redirecionamento não é seguido). O tempo total de espera é de cerca de 60 s, seguido de uma janela de estabilização (cerca de 30 s) em que o container não pode cair.

Faça o endpoint responder rápido e sem efeito colateral: `200 OK` sem consultar nada, ou no máximo um `SELECT 1`. **Não** rode migration, aquecimento pesado nem chamada a terceiros dentro dele. Um app que só abre a porta depois de terminar um trabalho longo falha em `activate_no_http`.

### 5. Shutdown gracioso no `SIGTERM`

Ao trocar de versão, a plataforma envia `SIGTERM` ao container antigo (e `SIGKILL` depois de um prazo curto, na ordem de segundos). O app deve parar de aceitar conexões novas, terminar as requisições em andamento e sair com código 0.

Em Go, `signal.NotifyContext(ctx, syscall.SIGTERM)` + `srv.Shutdown(ctx)`; em Node, `process.on("SIGTERM", () => server.close(() => process.exit(0)))`. Evite `npm start` encadeado em shell: o sinal pode não chegar ao app.

### 6. Logs no stdout, em JSON

A plataforma lê stdout/stderr ([Logs](/operacao/logs/)), mascarando valores sensíveis. Não grave arquivo de log. Uma linha JSON por evento, com `request_id`. Em falha de boot, logue a causa antes de sair: o erro do deploy usa as últimas linhas do container.

### 7. Assets e dados gerados entram no BUILD, nunca no boot

O diretório do app (`/app`) é **somente leitura** em runtime. Tudo que o app precisa ter em disco tem de existir quando o container sobe.

Caso real: uma aplicação de música tentava baixar o SoundFont (`scripts/get-soundfont.sh`) ao iniciar e gravar em `data/soundfonts/FluidR3_GM.sf2`. O boot falhava com `open data/soundfonts/...: no such file or directory` e o deploy terminava em `activate_app_crashed`. Caminhos corretos:

1. **Baixar no build** (`build_command` ou etapa do `Dockerfile`), fixando versão e hash, e ler de dentro do artefato.
2. **Commitar** o arquivo, se o tamanho permitir.
3. Se é grande e não muda por deploy, baixar **uma vez** para um volume e reaproveitar.

Nunca: baixar ou gerar em `/app/...` no boot.

### 8. Escreva só em `/tmp` ou no volume

- `/tmp`: 64 MB, na memória, sem exec, apagado a cada reinício e deploy.
- Volume de serviço: sobrevive a deploys, mas é de **um** serviço. Serve para dados que não precisam ser vistos por outra cópia (ex.: arquivo [SQLite](/bancos/sqlite/), cache refazível).

Se o app grava em `/app/data`, crie o volume nessa pasta ou leia o caminho de uma variável (`DATA_DIR`), nunca fixo no código.

### 9. Idempotência

Requisições chegam duas vezes (retry, deploy no meio da chamada). Aceite `Idempotency-Key` com `UNIQUE` no banco, use `INSERT ... ON CONFLICT DO NOTHING` e registre efeitos externos (e-mail, cobrança) como "já enviado".

### 10. Sem cron interno

Não há agendador nem worker gerenciado, e `setInterval`/cron dentro do app reinicia a cada deploy e rodaria N vezes com réplicas. Alternativas: um **agendador externo** (cron na internet ou GitHub Actions `schedule`) chamando um endpoint idempotente (`POST /internal/jobs/limpeza` com segredo no cabeçalho e lock no banco); trabalho sob demanda disparado pela ação do usuário; ou **fila no banco** (veja abaixo). O serviço de worker também precisa responder HTTP hoje.

### 11. Migrations idempotentes e compatíveis

No blue/green a versão antiga e a nova convivem por segundos no **mesmo banco**. Faça migrations idempotentes e protegidas por **advisory lock** (duas cópias subindo juntas não migram duas vezes), em dois tempos (adicione a coluna antes de usá-la; remova a antiga só no deploy seguinte) e sem migração pesada no boot, que atrasa o health check ([Migrações](/bancos/migracoes/)).

## Pronto para réplicas (quando existirem)

Réplicas **não existem hoje**. Quando existirem, o tráfego será dividido entre cópias idênticas, sem afinidade: duas requisições do mesmo usuário podem cair em cópias diferentes. Cada linha abaixo é um defeito latente desse dia.

| Se o app faz isto | Com N cópias vira | Faça isto |
|---|---|---|
| Sessão em memória ou em arquivo | usuário "desloga" ao cair em outra cópia | token assinado (JWT/cookie assinado) ou tabela de sessões no banco gerenciado |
| Upload gravado em `/tmp`, no disco ou no volume do serviço (que é de uma cópia só) | arquivo existe só em uma cópia e some no reinício ou não é visto pelas outras | envie direto para a [CDN/galeria](/cdn/visao-geral/) ou outro armazenamento de objetos por API, e guarde só a referência no banco |
| Fila ou lock em memória | dois consumidores pegam o mesmo item | fila no banco (`FOR UPDATE SKIP LOCKED`) e lock pelo banco (`pg_advisory_lock`) |
| Job periódico dentro do app | roda N vezes | agendador externo chamando endpoint idempotente, com lock no banco |

### Fila e lock no banco (Postgres)

```sql
UPDATE jobs SET status = 'running', started_at = now()
WHERE id = (
  SELECT id FROM jobs WHERE status = 'pending'
  ORDER BY created_at LIMIT 1
  FOR UPDATE SKIP LOCKED
)
RETURNING *;

```

Use pool de conexões pequeno por cópia (5 a 10): com N cópias o total é N vezes o pool e o banco tem limite de conexões.

## Rede e egress

Serviços do projeto se falam pelo nome ([Rede privada](/conectados/rede-privada/)). Saída para a internet é permitida; **bloqueados**: SMTP direto (use e-mail por API HTTPS), rede interna, host e metadados da nuvem ([Isolamento](/seguranca/isolamento/)). 

## Checklist: meu app está pronto para a Nebular?

- [ ] Escuta em `0.0.0.0` na porta de `PORT` e a `port` do serviço bate com ela.
- [ ] `healthcheck_path` responde 2xx/3xx rápido, sem trabalho pesado.
- [ ] Nada é gravado em `/app`; escritas vão só para `/tmp` ou para o volume, e o caminho vem de variável de ambiente.
- [ ] Assets, modelos e arquivos gerados são baixados ou criados **no build** (ou commitados).
- [ ] Toda config e todo segredo vêm de variável; `DATABASE_URL` vem da referência do banco.
- [ ] O boot não depende de outro serviço estar de pé (tenta de novo e degrada em vez de abortar).
- [ ] `SIGTERM` encerra o app limpo em poucos segundos.
- [ ] `resources.memory_mb`/`cpus` declarados com folga para o pico (o estouro de memória reinicia o container).
- [ ] Migrations idempotentes, com lock e compatíveis com a versão anterior.
- [ ] Sem cron, fila ou lock em memória; sem sessão ou upload em disco local.

## Erros comuns

Um deploy que falha termina em `failed` com um `error.code` estável ([Deploys e status](/operacao/deploys-e-status/)); leia também o log de build e do container ([Logs](/operacao/logs/)). A **versão anterior continua no ar**.

| `error.code` | Causa mais comum | Correção |
|---|---|---|
| `activate_readonly_write` | o app tentou gravar em `/app/...` (`EROFS`, `mkdir`, `open ...: read-only file system`) | gravar em `/tmp`; ou criar um volume na pasta indicada pela mensagem; ou gerar o arquivo no build |
| `activate_app_crashed` | o processo caiu logo ao iniciar: variável ausente, arquivo ausente (asset não gerado no build), exceção no boot, banco inalcançável | ler a "primeira linha de erro" na mensagem e o log do container; definir a variável; incluir o arquivo no build; tratar a falha de conexão sem abortar |
| `activate_no_http` | o app roda mas não respondeu na porta: escuta em `127.0.0.1`/outra porta, ou demora a abrir a porta, ou `healthcheck_path` devolve 4xx/5xx | escutar em `0.0.0.0:$PORT`; declarar `port`; abrir a porta primeiro e fazer o trabalho pesado depois; corrigir o caminho do health check |
| `activate_oom` | o app usou mais memória que o limite do serviço | subir `resources.memory_mb`, reduzir caches e concorrência; novo deploy |
| `image_requires_root` | a imagem exige root (container encerrou nos primeiros 30 s) | declarar `build.user` (`uid[:gid]`, nunca root) ou usar uma variante sem privilégio |
| `build_failed` e família (`build_install_failed`, `build_script_failed`, `build_detect_failed`, `build_clone_failed`, `build_copy_failed`) | instalação de dependência, script de build ou detecção do builder falhou | ler o log de build; fixar versões; declarar `build.builder`/`build_command`; `root_dir` correto em monorepo |
| `build_oom`, `build_timeout`, `build_disk_full` | o build estourou memória, tempo ou disco | reduzir paralelismo e o que entra no artefato; tirar etapas pesadas do build |
| `unresolved_reference` (`422` ao disparar o deploy) | `${{svc.VAR}}` aponta para variável ou serviço que não existe | criar a variável/serviço ou corrigir o nome ([Tabela de erros](/erros/tabela/)) |

## Para agents

Confirme `PORT`, escrita só em `/tmp`/volume e config por variável antes de codar; gere assets no build; não crie cron nem fila em memória (proponha agendador externo); não diga que o app "tem réplicas" (hoje há uma cópia por serviço); em falha, leia `error.code` antes de mexer no código.

---

URL: https://docs.nebularws.com/seguranca/isolamento.md

# Isolamento

Cada time, projeto e serviço roda isolado dos demais. Esta página diz **o que você pode assumir** (e o que não deve tentar). Ela não lista regras internas: o objetivo é você projetar o app certo, não conhecer a parede.

## Serviços: um container, sem privilégio

- **Um serviço = um container próprio**, sem root. Se a imagem pede root, a plataforma o força a um usuário sem privilégio; se o app não funcionar assim, o deploy falha com `image_requires_root` e a ação é declarar `build.user` ([Tabela de erros](/erros/tabela/#deploy-failed-e-blocked)).
- **Sistema de arquivos somente leitura.** Escreva em `/tmp` (memória, pequeno) ou em um [volume](/conectados/volumes/). Dados fora do volume somem a cada deploy.
- **Sem capabilities extras** e sem escalar privilégio: não há `sudo`, `setuid` útil, montar discos, mexer em rede ou em módulos do kernel. Portas abaixo de 1024 não são acessíveis ao app.
- **Sandbox de kernel.** Os containers rodam sob um runtime com sandbox (gVisor), de modo que uma falha no app não chega ao kernel do host. Algumas chamadas de sistema exóticas não existem; apps comuns (web, workers, bancos embarcados) não notam.
- **Limites de recursos** por serviço: memória, CPU e número de processos/threads. Estourar a memória reinicia o container (veja o log de execução); um *fork bomb* só derruba o próprio serviço. Os máximos dependem do plano ([Limites e cotas](/operacao/limites-e-cotas/), [Escala e recursos](/operacao/escala-e-recursos/)).

## Rede

- **Cada projeto tem a sua rede privada.** Os serviços do mesmo projeto se encontram pelo `name` ([Rede privada](/conectados/rede-privada/)). **Serviços de outros projetos e de outros times não são alcançáveis**, nem pelo nome nem pelo IP.
- Serviço `private` não tem rota pública; só `public` recebe URL e domínio.
- O app **não alcança** o host da plataforma, a rede interna da infraestrutura nem os endpoints de metadados da nuvem. O tráfego de saída para a internet pública é permitido, com uma exceção prática: **envio direto de e-mail por SMTP é bloqueado**. Use um provedor de e-mail por API HTTPS.
- Entrada: só o proxy da plataforma fala com o seu app, por HTTPS na borda. Confie em `X-Forwarded-*` apenas vindo dele.

## Volumes

Cada volume pertence a **um serviço** e só ele o monta. Há cota de tamanho. O volume é preservado entre deploys.

## Bancos gerenciados

Cada banco é uma instância lógica **só sua**: usuário e credencial próprios, sem privilégios administrativos, conexão **somente com TLS** e **somente a partir de origens autorizadas** (os serviços do seu projeto). Uma credencial abre o seu banco e nenhum outro: nem os de outros projetos do mesmo time. Não há `SUPERUSER`, `CREATE ROLE/DATABASE`, leitura de arquivos do servidor nem execução de programas. Esperam-se erros de permissão se você tentar. Quando o banco atinge a cota (`quota_mb`) ele vira somente leitura até você reduzir os dados ([Bancos](/bancos/postgres/)).

Ao rotacionar a credencial, a antiga deixa de valer.

## Times e projetos na API

- Todo recurso pertence a um time. **Recurso de outro time responde `404`, nunca `403`**: não é possível descobrir se um id existe. Não varie ids para "testar".
- O **token** carrega o time e (opcional) os projetos permitidos; o servidor ignora qualquer `team_id`/`project_id` enviado no corpo. Escopos finos por rota ([Tokens e escopos](/seguranca/tokens-e-escopos/)).
- Valores sensíveis de variáveis só saem com o escopo `env:reveal` (e, para criá-lo, confirmação forte de uma pessoa). Respostas de recusa nunca carregam segredo nem dados do recurso alheio.
- Referências `${{svc.VAR}}` só enxergam o **próprio projeto**; apontar para outro projeto ou time responde `422 unresolved_reference`.
- Parâmetros de template e valores de variável são tratados como **texto literal**: `${{...}}` dentro de um parâmetro não vira referência.

## Como isso testa

A plataforma roda continuamente suítes que tentam atravessar essas paredes (containers que atacam vizinhos, credenciais de banco usadas fora do seu banco, tokens de um time em recursos de outro). Se você achar um caminho que atravessa, é uma falha de segurança: reporte pelo canal descrito em [Reportar abuso](/seguranca/reportar-abuso/) (`security` no assunto) em vez de explorar.

## O que isso significa para o seu agent

1. Escreva só em `/tmp` ou no volume; não dependa de root.
2. Fale com outros serviços do projeto pelo nome; use `private` para o que não deve ter URL.
3. Use as credenciais de banco entregues por variável (referências `${{db.…}}`, veja [Conexão e referências](/bancos/conexao-e-referencias/)), nunca outras.
4. `404` em recurso que "deveria existir" quase sempre é id ou time errado: liste com `GET` e use o id devolvido.

---

URL: https://docs.nebularws.com/seguranca/o-que-nao-e-permitido.md

# O que não é permitido

Rodar apps de terceiros exige limites claros. Esta é a política em linguagem direta, para pessoas e para agents. O que está listado como **bloqueado** não funciona por construção; o restante é proibido pela política e sujeito a suspensão.

## Proibido

- **Mineração de criptomoedas** e qualquer carga cujo objetivo é consumir CPU/GPU alheios.
- **Spam, phishing, fraude** e hospedagem de páginas que imitam outras marcas ou bancos; distribuição de **malware**, *botnets*, C2 ou *exploit kits*.
- **Ataque a terceiros**: varredura de portas, DDoS, *credential stuffing*, *scraping* abusivo, uso do serviço como proxy aberto ou *relay*.
- **Atacar a própria plataforma**: tentar sair do container, alcançar o host, outros projetos ou outros times, ler credenciais que não são suas, contornar cotas e *rate limits*, ou testar ids de outros times.
- **Conteúdo ilegal**, incluindo material de exploração de menores, e conteúdo que viola direitos de terceiros.
- **Revender acesso** à sua conta ou compartilhar tokens além do necessário. Tokens são pessoais do time e devem ter o menor escopo possível.
- **Envio de e-mail em massa** pela plataforma (o SMTP direto é bloqueado; provedores de e-mail têm as próprias regras).

## O que a plataforma bloqueia por construção

| Tentativa | Resultado |
|---|---|
| Rodar como root, `setuid`, montar discos, carregar módulos | negado; imagem que exige root falha com `image_requires_root` |
| Escrever fora de `/tmp` e dos volumes | erro de sistema de arquivos somente leitura |
| Acessar serviços de outros projetos/times, o host ou metadados da nuvem | sem rota |
| SMTP direto de saída | bloqueado |
| Consumir mais memória/CPU/processos que o plano | o container é reiniciado ou limitado |
| Credencial de banco fora do banco dela, privilégios administrativos de banco | `permission denied` |
| Recurso de outro time na API | `404` |
| Rota sem o escopo do token | `403` |
| Arquivos com malware, SVG ativo, compactados bomba ou cifrados na CDN | recusados com `422` ([Tabela de erros](/erros/tabela/)) |
| Excesso de requisições ou de deploys por hora | `429` com `Retry-After` |

Tentar repetidamente algo bloqueado só gera ruído e alertas: **não é um modo de testar a plataforma**.

## O que acontece se você violar

Conteúdo ou serviço em violação pode ser **retirado do ar sem aviso prévio** quando houver risco a terceiros ou à plataforma; reincidência ou violação grave leva à **suspensão do time**. Quando possível avisamos o contato do time e damos prazo para corrigir. Apps que se comportam como bots de ataque são tratados primeiro e conversados depois.

## Dúvida ou denúncia

- Achou conteúdo malicioso servido pela CDN? [Reportar abuso](/seguranca/reportar-abuso/) (`POST /v1/abuse`, público).
- Achou uma falha de segurança na plataforma? Não explore: reporte por `abuse@nebularws.com` com o assunto `security`.
- Não sabe se o seu caso é permitido? Pergunte antes por esse mesmo contato. Para um agent: quando um pedido do usuário parece cair numa das categorias acima, **pare e avise a pessoa** em vez de tentar contornar o erro.

---

URL: https://docs.nebularws.com/seguranca/tokens-e-escopos.md

# Tokens e escopos

## Escopos

| Escopo | Permite |
|---|---|
| `assets:read` | listar galerias e arquivos, consultar detalhes e status de varredura |
| `assets:write` | enviar, versionar e excluir arquivos |
| `galleries:manage` | criar galerias (um token restrito a galerias específicas **não** cria galeria: 403) |
| `projects:read` | listar e ler projetos, serviços, deploys, domínios e bancos |
| `projects:write` | criar, editar e apagar projetos e serviços |
| `deploy` | disparar deploy e rollback, enviar fonte |
| `env:read` | ler nomes e valores **não sensíveis** de variáveis |
| `env:write` | criar, alterar e apagar variáveis |
| `env:reveal` | ver valores sensíveis (`?resolved=true`): exige que o token tenha sido criado com step-up **e** com este escopo explícito |
| `domains:write` | anexar e remover domínios |
| `volumes:write` | criar e apagar volume |
| `databases:write` | criar, apagar, rotacionar credencial, backup e restore de bancos |
| `logs:read` | ler logs de build e de runtime |
| `templates:deploy` | instanciar templates (ex.: WordPress) |

Princípio do menor privilégio: peça só o que a tarefa usa. Um agent que só publica imagens na CDN precisa de `assets:write`, não de `deploy`.

## Restrições

- **Por projeto** (`project_ids`): o token só enxerga e age nos projetos listados. Os demais projetos do time respondem `404`, como se não existissem.
- **Por galeria**: o token só enxerga as galerias permitidas.

## Regras

- O token (`nbk_…`) é mostrado **uma única vez**; guardamos só o hash. Perdeu? Revogue e crie outro.
- Validade: 90 dias por padrão, máximo 1 ano. Pode ser revogado a qualquer momento.
- O token pertence ao **time**, não a uma pessoa, e nunca dá acesso a membros ou cobrança.
- Criar um token exige papel `admin` e confirmação recente de identidade (step-up).
- Valores sensíveis (senhas de banco, `DATABASE_URL`, segredos gerados) só aparecem em claro com `env:reveal`; sem ele ficam mascarados.
- Envie somente em `Authorization: Bearer`. **Nunca em query string** (recusado com 401). Cookies são ignorados.
- Guarde em segredo do ambiente (CI, cofre). Nunca em repositório, log ou prompt. Exemplos desta documentação usam sempre `nbk_EXEMPLO`.

## Verificar o que o token pode

```bash
curl -sS "$NEBULAR_API/v1/me" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```

`403 forbidden` = falta o escopo da rota (peça um token novo); `404` pode significar que o recurso está fora dos `project_ids` do token. Veja [Tabela de erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/seguranca/reportar-abuso.md

# Reportar abuso

Encontrou conteúdo malicioso hospedado em `*.nebularcdn.com`? `POST /v1/abuse` é **público** (sem token), com
rate-limit por IP. Campos: `url` (da CDN), `reason` e `contact` (opcional). O operador analisa e tira do ar.

```bash
curl -sS -X POST "$NEBULAR_API/v1/abuse" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png", "reason": "Página de phishing imitando um banco.", "contact": "denunciante@exemplo.org"}'
```
```json
{"status": "received"}
```

Também aceitamos denúncias em `abuse@nebularws.com`.

---

URL: https://docs.nebularws.com/erros/tabela.md

# Tabela de erros

Os códigos de arquivos/CDN (v12) estão logo abaixo; os da v13 vêm depois, por família.

Formato: `{"error": "<codigo>", "message": "..."}`; alguns trazem campos extras (`signature`, `reasons`).
Regra geral: **4xx = corrija a requisição, não repita igual** (exceto `429`); **5xx e `429` = repita com espera**.

| Código (`error`) | HTTP | Quando acontece | Ação recomendada |
|---|---|---|---|
| `unauthorized` | 401 | token ausente, malformado, expirado, revogado, enviado na query string ou só cookie | **Não repita.** Confira o cabeçalho `Authorization: Bearer nbk_…`; se expirou ou foi revogado, peça um token novo a um admin. A resposta é genérica de propósito. |
| `forbidden` | 403 | o token não tem o escopo da rota (ex.: `assets:read` tentando enviar) ou token restrito tentando criar galeria | **Não repita.** Peça um token com o escopo certo (`assets:read`, `assets:write`, `galleries:manage`). |
| `not_found` | 404 | galeria ou arquivo inexistente, de outro time, ou fora das galerias permitidas ao token (indistinguíveis) | Confira `key` da galeria e o `name` (use `%2F` para `/`). Não repita igual. |
| `invalid_request` | 400 | nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo | Corrija o dado (veja as regras de nome na [Limites e cotas](/operacao/limites-e-cotas/)). Não repita igual. |
| `bad_json` | 400 | corpo JSON malformado | Corrija o JSON e o `Content-Type: application/json`. |
| `unsupported_media_type` | 415 | `Content-Type` da requisição inesperado (ex.: JSON onde se espera `multipart/form-data`) | Use o `Content-Type` da rota (`multipart/form-data` no upload, `application/json` nos demais). |
| `payload_too_large` | 413 | arquivo acima de 25 MB ou imagem acima de 40 MP | Reduza/comprima o arquivo. Não repita igual. |
| `too_large` | 413 | corpo da requisição acima do limite aceito pelo servidor (antes de olhar o arquivo) | Envie um arquivo menor (máximo 25 MB). |
| `quota_exceeded` | 413 | cota do time estourada (5 GB ou 10 000 arquivos) | Exclua arquivos antigos (`DELETE`) ou peça aumento de cota. Repetir só funciona depois de liberar espaço. |
| `unsupported_type` | 415 | tipo não reconhecido ou imagem ilegível | Confira se o arquivo não está corrompido. Não repita igual. |
| `extension_mismatch` | 415 | a extensão declara uma classe e o conteúdo é outra (ex.: `.png` que é um executável) | Corrija o nome/extensão ou envie o arquivo certo. |
| `class_not_allowed` | 415 | a classe do arquivo não é permitida no bucket | Use outro tipo de arquivo ou outro bucket. Não repita igual. |
| `malware_detected` | 422 | antivírus, regras YARA ou reputação por hash detectaram ameaça (campo extra `signature`) | **Não reenvie.** O arquivo está infectado ou foi marcado; investigue a origem. A amostra não é guardada. |
| `svg_unsafe` | 422 | SVG com conteúdo ativo ou fora do padrão (campo extra `reasons[]`) | **Não reenvie o mesmo SVG.** Veja a [SVG recusado](/cdn/classes-de-arquivo-e-varredura/#por-que-meu-svg-foi-recusado-e-como-reexportar) e reexporte. |
| `archive_encrypted` | 422 | compactado cifrado ou que não temos como varrer | Envie sem senha. |
| `archive_bomb` | 422 | compactado acima dos limites (expansão, razão de compressão, número de entradas ou profundidade) | Divida ou reduza o pacote. Não reenvie igual. |
| `archive_unsupported` | 422 | formato compactado que não inspecionamos (7z, rar, xz, bzip2) | Reempacote como `.zip` ou `.tar.gz`. |
| `idempotency_conflict` | 409 (upload de galeria) / 422 (demais rotas) | mesma `Idempotency-Key` com outro corpo | Gere uma chave nova (ou envie o mesmo corpo de antes). |
| `rate_limited` | 429 | rate-limit por token ou por IP | **Repita** depois de `Retry-After` segundos (cabeçalho); sem o cabeçalho, espere 30 s e dobre a cada tentativa seguida, até 5 vezes. Reduza a concorrência. |
| `unavailable` | 503 | borda ou scanner indisponível | **Seguro repetir** (com `Idempotency-Key`): espere `Retry-After`; sem ele, backoff de 5, 10, 20, 40 s. Se persistir, pare e avise o time. |
| `authz_unavailable` | 503 | o motor de autorização falhou (a API nega por segurança em vez de arriscar) | Igual a `unavailable`: repita com backoff; é transitório. |

## Erros da v13 (projetos, serviços, deploys, bancos)

Mesmo formato `{"error", "message"}`. Legenda da ação: **corrigir** (altere a requisição), **repetir** (com espera), **parar** (peça a uma pessoa).

### Autenticação, autorização e anti-IDOR

| Código | HTTP | Significado | Ação |
|---|---|---|---|
| `unauthorized` | 401 | token ausente, inválido, expirado ou revogado. Resposta genérica de propósito | **parar**: não tente de novo com o mesmo token |
| `forbidden` | 403 | o token existe mas não tem o escopo da rota (`projects:write`, `deploy`, `env:write`, `env:reveal`, `domains:write`, `volumes:write`, `databases:write`, `logs:read`, `templates:deploy`) ou `env:reveal` sem step-up na criação do token | **parar**: peça um token com o escopo certo ([Tokens e escopos](/seguranca/tokens-e-escopos/)) |
| `not_found` | 404 | o recurso não existe **ou não é do seu time**, ou fica fora dos `project_ids` do token. Os casos são indistinguíveis de propósito (anti-IDOR) | **corrigir** o id/nome. **Nunca** tente descobrir qual dos casos é: variar ids para "testar" só gera ruído e 429 |

### Validação e conflito

| Código | HTTP | Significado | Ação |
|---|---|---|---|
| `invalid_request` | 400 | campo fora das regras (nome de serviço fora de `^[a-z][a-z0-9-]{0,30}$`, `source.type` ou `build.builder` desconhecido, `healthcheck_path` sem `/` inicial, comando acima de 1024 caracteres), **`Idempotency-Key` malformada** (fora de 8 a 128 caracteres `[A-Za-z0-9._:-]`; a `message` diz a regra) ou `image` do deploy sem `@sha256:` | **corrigir** o campo ou o cabeçalho citado na `message` |
| `bad_json` | 400 | corpo JSON malformado | **corrigir** |
| `name_taken` | 409 | já existe recurso com esse nome (serviço, banco, variável duplicada no lote…); todo projeto nasce com um serviço `web` | **corrigir**: escolha outro nome, ou use o existente |
| `deploy_in_progress` | 409 | já há um deploy em andamento para o serviço | **esperar**: acompanhe o deploy em andamento (polling) em vez de disparar outro |
| `nothing_to_rollback` | 409 | o deploy de destino do rollback não terminou com sucesso | **corrigir**: escolha um deploy `ready` |
| `backup_not_ready` | 409 | restore de um backup que ainda não terminou | **esperar**: consulte o job do backup até `done` |
| `domain_taken` | 409 | domínio já adicionado ao time ou ativo em outro projeto | **corrigir**: use a prova TXT de posse ([Domínio próprio](/dominios/dominio-proprio/)) |
| `slug_taken` | 409 | o slug público já está em uso | **corrigir**: escolha outro slug |
| `idempotency_conflict` | 422 | mesma `Idempotency-Key` com pedido diferente (chave malformada: `400 invalid_request`) | **corrigir**: gere chave nova |

### Referências entre variáveis (`${{svc.VAR}}`, `${{shared.VAR}}`)

Aparecem quando as referências são resolvidas, no **deploy**: o `POST` do deploy (de serviço ou de grupo) responde `422` com `details.references` (lista de nomes) e nada é criado. Veja [Variáveis e referências](/conectados/variaveis-e-referencias/).

| Código | Significado | Ação |
|---|---|---|
| `422 unresolved_reference` | referência a variável ou serviço inexistente (a lista diz quais) | **corrigir**: crie a variável ou o serviço, ou corrija o nome; refaça o deploy |
| `422 reference_cycle` | `A` referencia `B` que referencia `A` | **corrigir**: quebre o ciclo (use valor literal em um dos lados) |
| `422 invalid_reference` | `${{...}}` fora da forma `escopo.VAR` | **corrigir** a sintaxe |
| `422 reference_too_deep` | cadeia de referências com mais de 16 níveis | **corrigir**: achate a cadeia |
| `422 value_too_large` | valor expandido acima de 64 KiB ou ambiente total acima de 256 KiB | **corrigir**: reduza o valor |
| `service_not_found` | o serviço citado na referência não está no projeto | **corrigir** o nome do serviço |

### Cotas

| Código | HTTP | Contexto | Ação |
|---|---|---|---|
| `quota_exceeded` | 413 | arquivos: cota de 5 GB / 10 000 arquivos do time | liberar espaço (`DELETE`) ou **parar** e pedir aumento |
| `quota_exceeded` | 422 | banco: cota de tamanho do banco (`quota_mb`) atingida; o banco fica `read_only` até baixar do limite | **parar** a escrita; apague dados ou **parar** e peça aumento de cota. Não repita a escrita |
| `project_quota_exceeded` | 409 | o time atingiu o limite de projetos | apague um projeto que não usa ou **parar** e peça aumento |

### Bancos gerenciados

| Código | HTTP | Significado | Ação |
|---|---|---|---|
| `unavailable` | 503 | o motor do banco (ou o nó) está indisponível | **repetir** com backoff (5, 10, 20, 40 s, até 5 vezes). Se persistir, **parar** e avisar |
| `backup_not_ready` | 409 | restore de um backup que ainda não terminou | aguarde o job do backup terminar (`GET .../jobs/{j}`) e refaça |
| `not_found` | 404 | banco, backup ou serviço inexistente ou de outro time | **corrigir** o id |

### Deploy: `failed` e `blocked`

Um deploy não devolve erro HTTP quando falha: ele termina no estado `failed` ou `blocked` ao consultar `GET .../deployments/{d}` (veja [Deploys e status](/operacao/deploys-e-status/)).

| Estado | Significado | Ação |
|---|---|---|
| `failed` | build, resolução de referências ou subida falhou | leia o log de build (`GET .../deployments/{d}/logs`) e o log de runtime (`GET .../services/{s}/logs`, escopo `logs:read`); **corrigir** a causa e dispare novo deploy |
| `blocked` | um serviço do qual este depende falhou no deploy de grupo | corrija o serviço que falhou primeiro; depois refaça o deploy do grupo |
| `failed` com `error.code = team_app_limit` | o time já roda o máximo de apps do plano (a mensagem diz "N de M") | pare ou remova um app, ou peça ao operador para ampliar o limite; depois repita o deploy |
| `failed` com `error.code = image_requires_root` | a imagem declara (ou assume) root; a plataforma a forçou a rodar como `65534` e o container encerrou nos primeiros 30 s | **corrigir**: declare `build.user` no serviço (`uid[:gid]`, nunca root) com um usuário que a imagem suporte, ou troque por uma variante sem privilégio; depois dispare novo deploy |
| `canceled`, `superseded` | substituído por um deploy mais novo | nada a fazer; acompanhe o mais novo |

### Limites de taxa e indisponibilidade

| Código | HTTP | Significado | Ação |
|---|---|---|---|
| `rate_limited` | 429 | limite por token ou IP; também o limite de deploys por hora do plano (`deploys_per_hour`) em deploy, rollback e deploy de grupo (o `Retry-After` é o tempo até abrir vaga) | **repetir** após `Retry-After` segundos; sem o cabeçalho, 30 s dobrando; reduza a concorrência. Veja [Rate limit e retry](/erros/rate-limit-e-retry/) |
| `unavailable` | 503 | serviço interno indisponível | **repetir** com backoff; persistindo, **parar** |

Respostas de exemplo (todas reproduzidas e conferidas pelo teste do guia):

```bash
curl -sS "$NEBULAR_API/v1/galleries" -H "Authorization: Bearer nbk_invalido"
```
```json
{"error": "unauthorized", "message": "Token de API ausente ou inválido."}
```

```bash
curl -sS "$NEBULAR_API/v1/galleries/nao-existe-0000/assets" -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"error": "not_found", "message": "Recurso não encontrado."}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -F "file=@logo.png" -F "name=Logo Final.PNG"
```
```json
{"error": "invalid_request", "message": "Dados inválidos. Confira o nome e os campos enviados."}
```

```bash
# uma imagem acima do limite de megapixels
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@huge.png"
```
```json
{"error": "payload_too_large", "message": "O arquivo excede o limite de 25 MB."}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@photo.png.exe"
```
```json
{"error": "extension_mismatch", "message": "A extensão .png não corresponde ao conteúdo do arquivo."}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@app.exe"
```
```json
{"error": "class_not_allowed", "message": "Esta classe de arquivo não é permitida neste bucket."}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@eicar.bin"
```
```json
{"error": "malware_detected", "message": "Arquivo recusado: Win.Test.EICAR_HDB-1 detectado.", "signature": "Win.Test.EICAR_HDB-1"}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@unsafe.svg"
```
```json
{"error": "svg_unsafe", "message": "SVG recusado: contém <script>.", "reasons": ["script_element"]}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@locked.zip"
```
```json
{"error": "archive_encrypted", "message": "Arquivos compactados cifrados não podem ser varridos e são recusados."}
```

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries/$GALLERY/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -F "file=@bomb.zip"
```
```json
{"error": "archive_bomb", "message": "Arquivo compactado recusado: excede os limites de expansão."}
```

Os demais códigos (`forbidden`, `quota_exceeded`, `unsupported_type`, `archive_unsupported`, `rate_limited`,
`unavailable`, `authz_unavailable`, `bad_json`, `unsupported_media_type`, `too_large`) têm o mesmo formato.

---

URL: https://docs.nebularws.com/erros/rate-limit-e-retry.md

# Rate limit e retry

- **Repita** apenas `429` e `5xx` (`503 unavailable`, `503 authz_unavailable`, `503 unavailable`). Todo outro `4xx` exige corrigir a requisição.
- Em `429`, espere o número de segundos do cabeçalho `Retry-After`. Sem o cabeçalho, espere 30 s e dobre a cada tentativa seguida, até 5 vezes. Reduza a concorrência.
- Em `503`, espere `Retry-After`; sem ele, use backoff de 5, 10, 20, 40 s. `unavailable` (banco) segue a mesma regra. Se persistir, pare e avise uma pessoa.
- Use **`Idempotency-Key`** em todo `POST` que cria: repetir a mesma chave com o mesmo corpo devolve a mesma resposta e não duplica. Mesma chave com outro pedido: `422 idempotency_conflict` (no upload de galeria, `409`).
- Um laço de lote completo, com 429, `Retry-After` e idempotência, está em [Galerias e arquivos](/cdn/galerias/#b-subir-em-lote-com-laço-shell-429-retry-after-e-idempotência).

## Polling de deploy com backoff

Não há webhooks neste ciclo: consulte `GET /v1/projects/{p}/services/{s}/deployments/{d}` até o estado ser final (`ready`, `failed`, `blocked`, `canceled`, `superseded`). Comece em 2 s, dobre até 30 s, desista após 20 minutos e peça uma pessoa. Estados não finais: `queued`, `building`, `deploying`. Para um deploy de **grupo**, consulte `GET /v1/projects/{p}/group-deployments/{g}`: `running` é o único não final; `ready`, `failed`, `canceled` e `superseded` são finais. Um `429` ou `503` durante o polling segue as regras acima e não interrompe o deploy, que continua no servidor.

```bash
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\": \"rl1-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d '{"source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
D=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" -H "$H" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

delay=2; deadline=$(( $(date +%s) + 1200 ))
while :; do
  state=$(curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" \
    -H "$H" | jq -r '.status')
  case "$state" in
    ready) echo "no ar"; break ;;
    failed|blocked|canceled|superseded) echo "terminou em $state"; exit 1 ;;
  esac
  [ "$(date +%s)" -lt "$deadline" ] || { echo "tempo esgotado"; exit 1; }
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
```

---

URL: https://docs.nebularws.com/erros/fluxo-de-diagnostico.md

# Fluxo de diagnóstico

1. A resposta é `401`? **Pare.** O token está ausente, expirado, revogado ou fora do cabeçalho. Confira o cabeçalho; se persistir, peça um token novo a um admin.
2. É `403`? **Pare.** Falta escopo (`projects:write`, `deploy`, `env:write`, `env:reveal`, `domains:write`, `volumes:write`, `databases:write`, `logs:read`, `templates:deploy`, `assets:*`). Peça um token com o escopo da rota ([Tokens e escopos](/seguranca/tokens-e-escopos/)).
3. É `404`? O recurso não existe **ou não é do seu time**: os dois casos são indistinguíveis. Confira o id/nome que você usou (listando com `GET`) e **não** tente adivinhar ids.
4. É `429` ou `503` (`unavailable`, `authz_unavailable`, `unavailable`)? **Repita** com espera ([Rate limit e retry](/erros/rate-limit-e-retry/)).
5. É `409`? `name_taken` / `slug_taken`: outro nome ou slug. `project_quota_exceeded`: pare e peça aumento. `deploy_in_progress`: acompanhe o deploy em andamento. `nothing_to_rollback`, `backup_not_ready`: o destino ainda não terminou com sucesso; espere. Outros `409`: leia o estado do recurso antes de agir. (`idempotency_conflict` é `422` nas rotas de plataforma: gere chave nova.)
6. É `400`, `413`, `415`? Corrija o dado e envie de novo; não repita igual. Consulte a [tabela de erros](/erros/tabela/).
7. É `422`? Arquivos (`malware_detected`, `svg_unsafe`, `archive_*`): não reenvie o mesmo arquivo; SVG, veja [como reexportar](/cdn/classes-de-arquivo-e-varredura/#por-que-meu-svg-foi-recusado-e-como-reexportar); malware, avise uma pessoa. Banco: `quota_exceeded` ⇒ pare de escrever e peça aumento.
8. Upload `202 pending`? Não reenvie: consulte o arquivo com backoff até `scan.status` mudar ([Uploads pending](/cdn/galerias/#uploads-pending-202-como-esperar)).
9. `422 unresolved_reference`, `reference_cycle`, `invalid_reference`, `reference_too_deep` ou `value_too_large` ao disparar o deploy? Nada foi criado: `details.references` lista os nomes; corrija as variáveis e dispare de novo. Deploy terminou em `failed`? Leia o log de build e o de runtime (`error.code` e `error.message` do deployment dizem a causa). Com `error.code = image_requires_root`, declare `build.user` (uid[:gid], nunca root) ou troque a imagem. Um `429` ao disparar deploy pode ser o limite `deploys_per_hour`: espere o `Retry-After`. Depois dispare novo deploy.
10. Deploy em `blocked`? Outro serviço do grupo falhou: corrija o que falhou primeiro.
11. URL da CDN respondendo `451`? O arquivo foi retirado por segurança. Não insista; avise uma pessoa.

---

URL: https://docs.nebularws.com/receitas/do-zero-ao-ar-com-um-agent.md

# Do zero ao ar com um agent

## Prompt para colar no agent

```text
Você vai publicar um app na Nebular usando a API https://api.nebularws.com (rotas /v1).
Regras:
- Leia a documentação em https://docs.nebularws.com/llms-full.txt antes de agir. Não invente rotas.
- Autentique com o cabeçalho Authorization: Bearer $NEBULAR_TOKEN (variável de ambiente). Nunca imprima o token, nem o coloque em URL, log ou arquivo versionado.
- Use Idempotency-Key em todo POST que cria.
- Decida pelo campo "error" das respostas. 4xx (exceto 429): corrija a requisição. 429 e 503: espere Retry-After. 401, 403 e quota_exceeded: pare e me avise.
- 404 pode significar "não existe" ou "não é seu": não tente descobrir qual.
- Depois de disparar o deploy, consulte o estado com backoff (2 s dobrando até 30 s) até ready, failed ou blocked. Em failed, leia os logs, corrija e tente de novo (no máximo 3 vezes).
- Confirme no fim com um GET na URL pública e mostre o resultado.
Tarefa: <descreva o app e a stack>.
```

## Sequência

1. **Token** com os escopos `projects:read`, `projects:write`, `deploy`, `env:write`, `logs:read` (mais `domains:write`, `volumes:write`, `databases:write` conforme a tarefa): [Token de API](/comecar/token/) e [Tokens e escopos](/seguranca/tokens-e-escopos/).
2. **Projeto e serviço, deploy e verificação**: o passo a passo com curl exato está em [Primeiro deploy](/comecar/primeiro-deploy/).
3. **Escolha o guia da sua stack**: [Next.js e Node](/guia/nodejs-next/), [Go](/guia/go/), [Rust](/guia/rust/), [Python](/guia/python/), [site estático](/guia/site-estatico/), [Dockerfile](/guia/dockerfile/), [imagem pública](/guia/imagem-publica/), [WordPress](/guia/wordpress/).
4. **Variáveis e rede privada** entre serviços: [Variáveis e referências](/conectados/variaveis-e-referencias/), [Rede privada](/conectados/rede-privada/).
5. **Banco**: [PostgreSQL](/bancos/postgres/), [MariaDB](/bancos/mariadb/), [SQLite](/bancos/sqlite/).
6. **Domínio**: [Subdomínio gerado](/dominios/subdominio-gerado/) ou [domínio próprio](/dominios/dominio-proprio/).
7. **Se algo falhar**: [tabela de erros](/erros/tabela/) e [fluxo de diagnóstico](/erros/fluxo-de-diagnostico/).

Receitas completas: [front Next + back Go + Postgres](/conectados/front-back-db/), [WordPress](/guia/wordpress/), [agente sobe imagens](/receitas/agente-sobe-imagens/).

---

URL: https://docs.nebularws.com/receitas/agente-sobe-imagens.md

# Agente sobe imagens na galeria

Objetivo: o agent envia imagens para uma galeria da CDN e entrega a URL pública ao app, sem montar URL à mão.

Token necessário: `galleries:manage` (criar galeria), `assets:write` (enviar), `assets:read` (consultar); para gravar a URL no serviço, `projects:write` e `env:write`.

## 1. Criar a galeria

Guarde o `key` devolvido: ele vai nas rotas. Cada chamada cria uma galeria nova; use `Idempotency-Key` para repetir com segurança.

```bash
curl -sS -X POST "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: receita-imagens-$(date +%s)-$RANDOM" \
  -H "Content-Type: application/json" \
  -d '{"name": "Imagens do site"}'
```
```json
{"id": "gal_01J9ZK5Q", "key": "imagens-do-site-k7p2", "name": "Imagens do site"}
```

| Erro | Ação |
|---|---|
| `403 forbidden` | falta `galleries:manage` (ou o token é restrito a galerias): peça outro token |
| `429` | espere `Retry-After` e repita |

## 2. Enviar, esperar e ler a URL

Envie com `Idempotency-Key` derivada do conteúdo. `201` já vem publicado; `202` é `pending` (não reenvie): consulte o arquivo com backoff (2 s, dobrando até 30 s) até `scan.status` ser `clean`. Só então `alias_url` e `url` existem. Use sempre o valor devolvido.

```bash
GAL=$(curl -sS -X POST "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: receita-imagens-b-$(date +%s)-$RANDOM" \
  -d '{"name": "Imagens do site"}' | jq -r '.key')

code=$(curl -sS -o resp.json -w '%{http_code}' -X POST "$NEBULAR_API/v1/galleries/$GAL/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: hero-$(cksum < hero.png | tr ' ' '-')" \
  -F "file=@hero.png" -F "name=site/hero.png")
echo "upload: $code"
delay=2
for attempt in 1 2 3 4 5 6 7 8; do
  status=$(curl -sS "$NEBULAR_API/v1/galleries/$GAL/assets/site%2Fhero.png" \
    -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.current.scan.status')
  [ "$status" = "pending" ] || break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$status" = "clean" ]
curl -sS "$NEBULAR_API/v1/galleries/$GAL/assets/site%2Fhero.png" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.alias_url'
```

| Resposta | Ação |
|---|---|
| `413 payload_too_large` / `quota_exceeded` | reduza a imagem (25 MB, 40 MP) ou libere espaço |
| `415`, `422` | arquivo recusado: não reenvie o mesmo; veja a [tabela de erros](/erros/tabela/) |
| `409 idempotency_conflict` | chave reutilizada com outro arquivo: gere outra |
| `scan.status = rejected` | pare: o arquivo foi recusado, `scan.reason` diz o motivo |

Detalhes de `pending`, lote e troca de imagem mantendo a `alias_url`: [Galerias e arquivos](/cdn/galerias/).

## 3. Entregar a URL ao serviço

Guarde a `alias_url` como variável do serviço (`env:write`); o app lê `ASSET_BASE_URL` e monta os caminhos. A alias sempre aponta para a versão atual, então trocar a imagem não exige novo deploy. Mudar o valor de uma variável marca o serviço como "precisa de redeploy" para pegar o valor novo.

```bash
NAME="imagens-$(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: proj-$NAME" -d "{\"name\": \"$NAME\"}" | 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", "source": {"type": "upload"}}' | jq -r '.id')
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/ASSET_BASE_URL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "https://media.nebularcdn.com/imagens-do-site-k7p2/site/"}'
```

No exemplo real, use o prefixo da `alias_url` obtida no passo 2 (a última linha do bloco anterior).

| Erro | Ação |
|---|---|
| `403 forbidden` | falta `projects:write` ou `env:write` |
| `404 not_found` | projeto/serviço inexistente ou de outro time: confira os ids; não tente adivinhar |
| `400 invalid_request` | nome do serviço fora de `^[a-z][a-z0-9-]{0,30}$` ou campo inválido |

---

URL: https://docs.nebularws.com/receitas/ci-github-actions.md

# CI com GitHub Actions

Guarde o token (escopos `deploy` e `projects:read`) como secret `NEBULAR_TOKEN` do repositório e os ids como variáveis (`NEBULAR_PROJECT`, `NEBULAR_SERVICE`). Nunca escreva o token no YAML. Crie o token com a menor permissão possível e restrinja a `project_ids`.

```yaml
name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      NEBULAR_API: https://api.nebularws.com
      NEBULAR_TOKEN: ${{ secrets.NEBULAR_TOKEN }}
      P: ${{ vars.NEBULAR_PROJECT }}
      S: ${{ vars.NEBULAR_SERVICE }}
    steps:
      - name: Disparar deploy
        run: |
          D=$(curl -fsS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/deployments" \
            -H "Authorization: Bearer $NEBULAR_TOKEN" \
            -H "Idempotency-Key: gh-${{ github.sha }}" \
            -H "Content-Type: application/json" -d '{}' | jq -r '.id')
          echo "D=$D" >> "$GITHUB_ENV"
      - name: Esperar o deploy
        run: |
          delay=2; deadline=$(( $(date +%s) + 1200 ))
          while :; do
            state=$(curl -fsS "$NEBULAR_API/v1/projects/$P/services/$S/deployments/$D" \
              -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.status')
            echo "estado: $state"
            case "$state" in
              ready) exit 0 ;;
              failed|blocked|canceled|superseded) exit 1 ;;
            esac
            [ "$(date +%s)" -lt "$deadline" ] || exit 1
            sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
          done
```

- A `Idempotency-Key` com o SHA do commit faz o re-run do job não criar um segundo deploy.
- `-f` do curl faz o job falhar em 4xx/5xx. Em `429`/`503`, repita o job (veja [Rate limit e retry](/erros/rate-limit-e-retry/)).
- Auto-deploy por git (webhook do GitHub) é a alternativa sem workflow, quando o serviço tem fonte `git`.
- Para ler o motivo de uma falha, consulte `GET .../deployments/{d}/logs` (`logs:read`).

Erros comuns: `401` (secret ausente ou expirado), `403` (falta o escopo `deploy`), `404` (ids errados ou fora dos `project_ids` do token). Veja a [tabela de erros](/erros/tabela/).

---

URL: https://docs.nebularws.com/receitas/migrar-de-outro-host.md

# Migrar de outro host

Não existe rota de importação automática neste ciclo: a migração é manual, com as rotas documentadas. Faça nesta ordem e mantenha o host antigo no ar até o fim.

1. **Serviço**: crie projeto e serviço e faça o primeiro deploy pelo guia da sua stack ([Primeiro deploy](/comecar/primeiro-deploy/)). Valide na URL gerada ([Subdomínio gerado](/dominios/subdominio-gerado/)).
2. **Variáveis**: recrie cada variável com `PUT /v1/projects/{p}/services/{s}/variables/{NOME}` (escopo `env:write`). Valores que vêm do banco ou de outro serviço, use referência `${{svc.VAR}}` em vez de copiar ([Variáveis e referências](/conectados/variaveis-e-referencias/)). Segredos: nunca em log nem em repositório.
3. **Banco**: crie o banco gerenciado ([PostgreSQL](/bancos/postgres/), [MariaDB](/bancos/mariadb/), [SQLite](/bancos/sqlite/)). Gere o dump no host antigo e restaure com as ferramentas do próprio motor (`pg_dump`/`psql`, `mariadb-dump`/`mariadb`) usando a `DATABASE_URL` do novo banco (TLS obrigatório). Faça um backup ([Backup e restore](/bancos/backup-restore/)) antes de qualquer restauração destrutiva.
4. **Arquivos**: suba mídia para uma galeria ([Galerias e arquivos](/cdn/galerias/)); arquivos persistentes do app vão em volume ([Volumes](/conectados/volumes/)).
5. **Teste**: rode a verificação do app na URL gerada; confira logs (`logs:read`).
6. **Domínio**: reduza o TTL do DNS antes, adicione o domínio ao serviço e aplique os registros que a API devolve ([Domínio próprio](/dominios/dominio-proprio/)).
7. **Virada**: congele escritas no host antigo, faça o dump final e restaure, aponte o DNS. Mantenha o host antigo por alguns dias.
8. **Rollback**: se algo falhar, devolva o DNS ao host antigo; no lado Nebular use [rollback](/operacao/rollback/).

---

URL: https://docs.nebularws.com/referencia/autenticacao.md

# Autenticação e visão geral (referência)

API pública da Nebular para **agents e automações**: gerencie **projetos, serviços, deploys, variáveis, domínios, volumes, bancos e templates** e as **galerias de arquivos** servidas pela CDN (`*.nebularcdn.com`). Todas as rotas ficam em `/v1`, usam apenas `Authorization: Bearer` e respondem JSON (`application/json; charset=utf-8`, sempre `Cache-Control: no-store`). Esta especificação é servida em `GET /v1/openapi.json` (pública) e é validada contra o código a cada mudança.

### Como obter um token
No painel: **Time → Configurações → Tokens de API**. A criação exige papel `admin` do time e confirmação recente de identidade (step-up). O token tem o formato `nbk_<…>`, é **exibido uma única vez** (guardamos apenas o hash SHA-256), vale 90 dias por padrão (máximo 1 ano) e pode ser revogado a qualquer momento. Ele pertence ao **time**, nunca a uma pessoa. Pode ser restrito a algumas galerias (`assets:*`) e/ou a alguns projetos (`project_ids`).

O token vai **somente** no cabeçalho `Authorization: Bearer nbk_…`. **Nunca** o envie em query string. Cookies são **ignorados** nestas rotas (não há CSRF por construção) e as rotas de sessão do painel não aceitam Bearer. Cada operação indica os escopos exigidos na extensão `x-required-scopes` (todos são necessários) e, quando um escopo opcional muda a resposta, em `x-optional-scopes`.

### Escopos
| Escopo | Permite |
|---|---|
| `assets:read` | listar galerias e arquivos, consultar detalhes e status de varredura |
| `assets:write` | enviar, versionar e excluir arquivos |
| `galleries:manage` | criar galerias |
| `projects:read` | ler projetos, serviços, deployments, domínios, volumes, bancos e backups |
| `projects:write` | criar, editar e apagar projetos e serviços |
| `deploy` | disparar, cancelar e reverter deploys (serviço e grupo), enviar código-fonte |
| `env:read` | ler variáveis (valores sensíveis vêm `null`) |
| `env:write` | criar, alterar e apagar variáveis |
| `env:reveal` | ler valores sensíveis, `resolved=true` e credenciais de banco. Exige `env:read` e que o token tenha sido criado com confirmação de identidade (step-up) |
| `domains:write` | anexar e remover domínios |
| `volumes:write` | anexar, aumentar e apagar o volume |
| `databases:write` | criar, alterar, apagar, rotacionar, backup e restore de bancos |
| `logs:read` | ler log de build e de execução |
| `templates:deploy` | listar e instanciar templates |

Token sem o escopo ⇒ `403 forbidden`. Projeto de outro time, ou fora dos `project_ids` do token, é **indistinguível de um projeto inexistente** (`404 not_found`). `GET /v1/me` e `GET /v1/limits` aceitam qualquer token válido.

### Projetos e serviços
`{p}` nas rotas aceita o **id** (26 caracteres) ou o **slug** do projeto; `{s}` aceita o **id** ou o **nome** do serviço. Todo projeto nasce com um serviço `web` padrão. Variáveis podem referenciar outros serviços com `${{servico.VAR}}` (ex.: `${{db.MYSQL_HOST}}`); essas referências definem a ordem do deploy de grupo e são validadas no disparo.

### Deploys são assíncronos
`POST …/deployments`, `POST …/deploy`, rollback, backup e restore respondem `202` com um recurso em andamento. Acompanhe por **polling** com backoff (comece em 2 s e dobre até 15 s; não há webhooks neste ciclo):

- deployment: `queued → building → deploying → ready`, ou `failed`, `blocked`, `canceled`, `superseded`; em `failed`, `error` traz `code`, `message` e `details`;
- deploy de grupo: `running → ready | failed | canceled`, com o estado de cada serviço em `items[].status`;
- job de banco: `queued → running → done | failed`;
- domínio: `pending_dns → verifying → active | error`.

### Idempotência
Todo `POST` que cria ou dispara aceita `Idempotency-Key` (8 a 128 caracteres `[A-Za-z0-9._:-]`). Mesma chave + mesmo pedido em 24 h devolve a **mesma resposta** (com `Idempotent-Replay: true`); mesma chave com pedido diferente ⇒ `422 idempotency_conflict`; chave malformada ⇒ `400`. Só respostas `2xx` são gravadas, então repetir depois de uma falha executa de verdade. O upload de arquivos de galeria tem regra própria (`409 idempotency_conflict`, mais abaixo).

### Paginação
Listas devolvem `{"items": […], "next_cursor": "…"|null, "has_more": bool}`. Passe `next_cursor` em `?cursor=` para a página seguinte e use `?limit=` de 1 a 200 (padrão 50). O cursor é opaco; cursor malformado ⇒ `400 invalid_request`. Deployments, backups e a lista de projetos vêm do mais novo para o mais antigo; as demais do mais antigo para o mais novo (variáveis por nome).

### Segredos
Variáveis marcadas `sensitive` nunca voltam em claro por padrão (`value: null`); a resposta de `PUT` nunca ecoa um valor sensível; logs saem com segredos mascarados. Credenciais de banco só saem em `POST …/credentials` (nunca `GET`), com `env:reveal`, e a leitura é auditada.

### Limites
- Plano do time: serviços, memória, volumes, bancos e deploys por hora (`GET /v1/limits`). Ao atingir ⇒ `422 quota_exceeded`.
- Corpo JSON até 16 KiB (variáveis até 96 KiB por variável e 1 MiB no lote; serviços e templates até 64 KiB); código-fonte (multipart) até 512 MB.
- **Galerias:** 25 MB por arquivo (imagens também limitadas a 40 megapixels); cota por time no bucket compartilhado de 5 GB e 10 000 arquivos. Nomes de arquivo: até 4 segmentos separados por `/` (3 barras), cada um em `[a-z0-9._-]`, até 200 caracteres, sem `..`, sem segmento iniciando com `.` e com o primeiro segmento diferente de 12 caracteres hexadecimais minúsculos; únicos dentro da galeria. Nome inválido ⇒ `400 invalid_request`.
- Rate-limit por token e por IP: ao receber `429`, espere `Retry-After` segundos.

### Classes de arquivo e como cada uma é servida
O tipo é detectado pelo **conteúdo** (magic bytes), nunca pela extensão ou pelo `Content-Type` enviado. Extensão divergente do conteúdo em executável/documento é recusada (`415 extension_mismatch`).

| Classe | Exemplos | Servido como |
|---|---|---|
| `image` | png, jpeg, webp, gif, avif | inline, transformável (`?w=`, `?q=`) |
| `svg` | svg | inline só se passar na varredura de SVG, com CSP restritiva |
| `font` | woff2, woff, ttf, otf | inline, CORS `*` |
| `media` | mp4, webm, mp3, ogg | inline, com `Accept-Ranges` |
| `document` | pdf, txt, csv, json | `Content-Disposition: attachment`; texto sempre `text/plain` |
| `markup` | html, htm, xhtml, xml | nunca renderiza: `attachment` + `text/plain` + CSP `sandbox` |
| `archive` | zip, tar.gz, 7z | `attachment`; arquivo cifrado ou impossível de varrer é recusado |
| `binary` | exe, msi, dmg, apk, deb, appimage, desconhecido | `attachment`, `application/octet-stream` |

### Varredura (nada é publicado antes de `clean`)
Todo upload entra em quarentena e passa por antivírus, regras YARA, reputação por hash (só o hash sai da nossa infra), varredura específica de SVG e decodificação segura de imagens. Detectado ⇒ `422` e a amostra não é guardada. Scanner indisponível ⇒ o arquivo fica `pending` e **não é publicado** (resposta `202`; consulte o `GET` do arquivo até `scan.status` sair de `pending`). Todo dia os arquivos publicados são reescaneados com as assinaturas novas: uma detecção move o arquivo para `quarantined` (deixa de ser servido, responde 451, o cache é purgado e o time é avisado).

### Erros
Todo erro tem o formato `{"error": "<code>", "message": "…", "details"?: {…}}`; `message` é legível (pt-BR) e `error` é **estável** para tratamento programático (enumerado em `Error.error`). Algumas respostas trazem `details` (ex.: `references` em `unresolved_reference`/`reference_cycle`: apenas nomes, nunca valores). Os `5xx` e `429` trazem `Retry-After` quando repetir faz sentido. Nos corpos de **serviço**, **variável** e **deploy**, um campo desconhecido (ex.: `memory_mb` solto no topo; o certo é `{"resources": {"memory_mb": 1024}}`) é recusado com `400 invalid_request`, e a mensagem nomeia o campo, em vez de ser ignorado em silêncio.

| Status | `error` |
|---|---|
| 400 | `invalid_request`, `bad_json`, `bad_body` |
| 401 | `unauthorized` (genérico de propósito: token ausente, inválido, expirado ou revogado) |
| 403 | `forbidden` |
| 404 | `not_found` |
| 409 | `name_taken`, `slug_taken`, `project_quota_exceeded`, `project_not_empty`, `deploy_in_progress`, `nothing_to_rollback`, `not_cancelable`, `sensitive_lowered`, `duplicate_variable`, `domain_taken`, `volume_exists`, `volume_in_use`, `volume_attached`, `backup_not_ready`, `gallery_not_empty`, `idempotency_conflict` (upload de galeria) |
| 413 | `too_large`, `payload_too_large` |
| 415 | `unsupported_media_type`, `unsupported_type`, `extension_mismatch`, `class_not_allowed` |
| 422 | `quota_exceeded`, `idempotency_conflict`, `unresolved_reference`, `reference_cycle`, `invalid_reference`, `reference_too_deep`, `value_too_large`, `malware_detected`, `svg_unsafe`, `archive_encrypted`, `archive_bomb`, `archive_unsupported` |
| 429 | `rate_limited` |
| 500 | `internal` |
| 503 | `unavailable`, `authz_unavailable`, `database_unavailable` |

### Espelho do painel
O painel usa as mesmas operações em `/api/teams/{tid}/…` (sessão + CSRF, com confirmação de identidade em ações destrutivas). Essas rotas não fazem parte desta API pública e não aceitam Bearer.

## Servidores

- `https://api.nebularws.com` — Produção

## Esquemas de segurança

- `bearer`: http (bearer) Token de API de time (`nbk_…`) criado em Time → Configurações → Tokens de API. Somente no cabeçalho `Authorization: Bearer`; nunca em query string. Cookies são ignorados nestas rotas.

---

URL: https://docs.nebularws.com/referencia/conta.md

# Conta (referência)

## GET `/v1/limits`

Plano e consumo

Plano do time e o uso de serviços, memória, volumes, bancos e deploys por hora. `used` > `max` nunca acontece: ao atingir, a criação responde `422 quota_exceeded` e um novo deploy responde `429 rate_limited` com `Retry-After`.

Qualquer token válido (nenhum escopo específico).

Escopo exigido: - · operationId: `getLimits`

### Resposta 200

Limites.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `plan` | string | sim |  |
| `services` | object | sim |  |
| `services.used` | integer | sim |  |
| `services.max` | integer | sim |  |
| `memory_mb` | object | sim |  |
| `memory_mb.used` | integer | sim |  |
| `memory_mb.max` | integer | sim |  |
| `volumes_gb` | object | sim |  |
| `volumes_gb.used` | integer | sim |  |
| `volumes_gb.max` | integer | sim |  |
| `databases` | object | sim |  |
| `databases.used` | integer | sim |  |
| `databases.max` | integer | sim |  |
| `deploys_per_hour` | object | sim |  |
| `deploys_per_hour.used` | integer | sim |  |
| `deploys_per_hour.max` | integer | sim |  |

```json
{
  "plan": "pro",
  "services": {
    "used": 3,
    "max": 20
  },
  "memory_mb": {
    "used": 1536,
    "max": 8192
  },
  "volumes_gb": {
    "used": 5,
    "max": 50
  },
  "databases": {
    "used": 1,
    "max": 5
  },
  "deploys_per_hour": {
    "used": 2,
    "max": 60
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/me`

Quem é o token

Devolve o token (id, nome, escopos, projetos permitidos, validade) e o time. Use para descobrir o que o token pode fazer antes de agir.

Qualquer token válido (nenhum escopo específico).

Escopo exigido: - · operationId: `getMe`

### Resposta 200

Token e time.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `token` | object | sim |  |
| `token.id` | string | sim |  |
| `token.name` | string | sim |  |
| `token.scopes` | array<string> | sim |  |
| `token.project_ids` | array\|null | sim | `null` = token com acesso a todos os projetos do time. |
| `token.expires_at` | string | não |  |
| `team` | object | sim |  |
| `team.id` | string | sim |  |
| `team.name` | string | sim |  |
| `team.plan` | string | sim |  |

```json
{
  "token": {
    "id": "01jb7kd15q8r7t2v4w6x8y0a3m",
    "name": "agente-deploy",
    "scopes": [
      "projects:read",
      "projects:write",
      "deploy"
    ],
    "project_ids": null,
    "expires_at": "2027-01-08T14:03:11Z"
  },
  "team": {
    "id": "01jb7h0000000000000000team",
    "name": "Acme",
    "plan": "pro"
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/openapi.json`

Esta especificação (OpenAPI 3.1 em JSON)

Serve esta própria especificação. Cache curto (5 minutos) e `ETag`. A versão YAML legível está no repositório (`docs/openapi.yaml`).

Endpoint **público**: não exige token.

Escopo exigido: - · operationId: `getOpenAPI`

### Resposta 200

Documento OpenAPI 3.1.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `openapi` | string | sim |  |
| `info` | object | sim |  |
| `paths` | object | sim |  |

### Resposta 304

`If-None-Match` igual ao `ETag` atual: sem corpo.

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/projetos.md

# Projetos (referência)

## GET `/v1/projects`

Lista os projetos

Projetos do time do token (ou só os permitidos, se o token for restrito), do mais novo para o mais antigo.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listProjects`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim | Id do projeto (26 caracteres). |
| `items[].name` | string | sim |  |
| `items[].slug` | string | sim |  |
| `items[].team_id` | string | sim |  |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
      "name": "Loja Acme",
      "slug": "loja-acme",
      "team_id": "01jb7h0000000000000000team",
      "created_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects`

Cria um projeto

Cria um projeto vazio no time. O projeto nasce com um serviço `web` padrão. Um token **restrito a projetos específicos** não pode criar (`403`): o novo ficaria fora da lista dele. Time inativo ⇒ `403`.

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `createProject`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `slug` | string | não | Opcional; gerado a partir do nome quando omitido. |

### Resposta 201

Projeto criado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do projeto (26 caracteres). |
| `name` | string | sim |  |
| `slug` | string | sim |  |
| `team_id` | string | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "Loja Acme",
  "slug": "loja-acme",
  "team_id": "01jb7h0000000000000000team",
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`slug_taken` (slug em uso) ou `project_quota_exceeded` (limite de projetos do time).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "name_taken",
  "message": "Já existe um serviço com esse nome no projeto."
}
```

### Resposta 422

`idempotency_conflict`: a mesma `Idempotency-Key` com outro corpo.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}`

Detalhe do projeto

Devolve o projeto. `{p}` aceita o id ou o slug.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getProject`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |

### Resposta 200

Projeto.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do projeto (26 caracteres). |
| `name` | string | sim |  |
| `slug` | string | sim |  |
| `team_id` | string | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "Loja Acme",
  "slug": "loja-acme",
  "team_id": "01jb7h0000000000000000team",
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PATCH `/v1/projects/{p}`

Renomeia o projeto

Renomeia o projeto (o slug não muda).

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `updateProject`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | não |  |

### Resposta 200

Projeto atualizado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do projeto (26 caracteres). |
| `name` | string | sim |  |
| `slug` | string | sim |  |
| `team_id` | string | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "Loja Acme",
  "slug": "loja-acme",
  "team_id": "01jb7h0000000000000000team",
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}`

Apaga o projeto

Apaga o projeto com serviços, containers, volumes, bancos e variáveis. **Irreversível.** Idempotente: repetir a chamada (pelo **id ou pelo slug**) para um projeto que este time já apagou pela API devolve `204`; um id ou slug que nunca foi visível ao token é `404`.

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `deleteProject`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Resposta 409

`project_not_empty`: ainda há recursos que impedem a remoção.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/servicos.md

# Serviços (referência)

## GET `/v1/projects/{p}/services`

Lista os serviços do projeto

Serviços do projeto, do mais antigo para o mais novo. `status` e `needs_redeploy` são derivados do estado atual.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listServices`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].project_id` | string | sim |  |
| `items[].name` | string | sim | Nome único no projeto (`^[a-z][a-z0-9-]{0,30}$`). |
| `items[].kind` | enum(app, database) | sim |  |
| `items[].engine` | enum(postgres, mariadb, sqlite) | não | Só `kind=database`. |
| `items[].visibility` | enum(public, private) | sim |  |
| `items[].slug` | string | não | Subdomínio público (`visibility=public`). |
| `items[].port` | integer | sim |  |
| `items[].source` | object | sim |  |
| `items[].source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `items[].source.repo` | string | não | `git`: `dono/repositório`. |
| `items[].source.branch` | string | não | `git`: branch implantada. |
| `items[].source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `items[].source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `items[].source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `items[].build` | object | sim |  |
| `items[].build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `items[].healthcheck_path` | string | não |  |
| `items[].start_command` | string | não |  |
| `items[].build_command` | string | não |  |
| `items[].resources` | object | sim |  |
| `items[].resources.memory_mb` | integer | sim |  |
| `items[].resources.cpus` | number | sim |  |
| `items[].auto_deploy` | boolean | sim |  |
| `items[].needs_redeploy` | boolean | sim | Variáveis ou configuração mudaram desde o último deploy. |
| `items[].status` | enum(idle, deploying, running, failed) | sim | Derivado do deployment mais recente. |
| `items[].public_url` | string | não |  |
| `items[].depends_on` | array<string> | sim | Nomes dos serviços referenciados por `${{svc.VAR}}`. |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
      "name": "web",
      "kind": "app",
      "visibility": "public",
      "slug": "loja",
      "port": 3000,
      "source": {
        "type": "git",
        "repo": "acme/loja",
        "branch": "main"
      },
      "build": {
        "builder": "auto"
      },
      "healthcheck_path": "/health",
      "resources": {
        "memory_mb": 512,
        "cpus": 0.5
      },
      "auto_deploy": true,
      "needs_redeploy": false,
      "status": "running",
      "public_url": "https://loja.nebularapps.com",
      "depends_on": [
        "db"
      ],
      "created_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services`

Cria um serviço de aplicação

Cria um serviço `kind=app`. Bancos nascem em `POST …/databases`. `visibility` omitido = `private` (fail-safe); serviço público exige `slug` e serviço privado não pode ter `slug`. Padrões: `port=3000`, 512 MB / 0,5 vCPU, `source={"type":"upload"}`, `build={"builder":"auto"}`.

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `createService`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `kind` | enum(app) | não | Só `app` (bancos nascem em `/databases`). |
| `visibility` | enum(public, private) | não | Padrão `private` quando omitido (nada fica público por omissão). `private` não pode ter `slug`. Em `public` o `slug` é opcional: omitido, a plataforma usa o nome do serviço se estiver livre (e não reservado), senão `<nome>-<4 caracteres aleatórios>`; o `slug` efetivo vem na resposta. |
| `slug` | string | não | Opcional quando `visibility=public` (derivado do nome do serviço se omitido; um slug explícito já em uso dá `409 slug_taken`). |
| `source` | object | não |  |
| `source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `source.repo` | string | não | `git`: `dono/repositório`. |
| `source.branch` | string | não | `git`: branch implantada. |
| `source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `build` | object | não |  |
| `build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `port` | integer | não |  |
| `healthcheck_path` | string | não |  |
| `start_command` | string | não |  |
| `build_command` | string | não |  |
| `resources` | object | não |  |
| `resources.memory_mb` | integer | sim |  |
| `resources.cpus` | number | sim |  |
| `auto_deploy` | boolean | não |  |

### Resposta 201

Serviço criado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `name` | string | sim | Nome único no projeto (`^[a-z][a-z0-9-]{0,30}$`). |
| `kind` | enum(app, database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | não | Só `kind=database`. |
| `visibility` | enum(public, private) | sim |  |
| `slug` | string | não | Subdomínio público (`visibility=public`). |
| `port` | integer | sim |  |
| `source` | object | sim |  |
| `source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `source.repo` | string | não | `git`: `dono/repositório`. |
| `source.branch` | string | não | `git`: branch implantada. |
| `source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `build` | object | sim |  |
| `build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `healthcheck_path` | string | não |  |
| `start_command` | string | não |  |
| `build_command` | string | não |  |
| `resources` | object | sim |  |
| `resources.memory_mb` | integer | sim |  |
| `resources.cpus` | number | sim |  |
| `auto_deploy` | boolean | sim |  |
| `needs_redeploy` | boolean | sim | Variáveis ou configuração mudaram desde o último deploy. |
| `status` | enum(idle, deploying, running, failed) | sim | Derivado do deployment mais recente. |
| `public_url` | string | não |  |
| `depends_on` | array<string> | sim | Nomes dos serviços referenciados por `${{svc.VAR}}`. |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "web",
  "kind": "app",
  "visibility": "public",
  "slug": "loja",
  "port": 3000,
  "source": {
    "type": "git",
    "repo": "acme/loja",
    "branch": "main"
  },
  "build": {
    "builder": "auto"
  },
  "healthcheck_path": "/health",
  "resources": {
    "memory_mb": 512,
    "cpus": 0.5
  },
  "auto_deploy": true,
  "needs_redeploy": false,
  "status": "running",
  "public_url": "https://loja.nebularapps.com",
  "depends_on": [
    "db"
  ],
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`name_taken` ou `slug_taken`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "name_taken",
  "message": "Já existe um serviço com esse nome no projeto."
}
```

### Resposta 422

`quota_exceeded` (limite de serviços do plano) ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}`

Detalhe do serviço

Devolve o serviço. `{s}` aceita o id ou o nome.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getService`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Resposta 200

Serviço.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `name` | string | sim | Nome único no projeto (`^[a-z][a-z0-9-]{0,30}$`). |
| `kind` | enum(app, database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | não | Só `kind=database`. |
| `visibility` | enum(public, private) | sim |  |
| `slug` | string | não | Subdomínio público (`visibility=public`). |
| `port` | integer | sim |  |
| `source` | object | sim |  |
| `source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `source.repo` | string | não | `git`: `dono/repositório`. |
| `source.branch` | string | não | `git`: branch implantada. |
| `source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `build` | object | sim |  |
| `build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `healthcheck_path` | string | não |  |
| `start_command` | string | não |  |
| `build_command` | string | não |  |
| `resources` | object | sim |  |
| `resources.memory_mb` | integer | sim |  |
| `resources.cpus` | number | sim |  |
| `auto_deploy` | boolean | sim |  |
| `needs_redeploy` | boolean | sim | Variáveis ou configuração mudaram desde o último deploy. |
| `status` | enum(idle, deploying, running, failed) | sim | Derivado do deployment mais recente. |
| `public_url` | string | não |  |
| `depends_on` | array<string> | sim | Nomes dos serviços referenciados por `${{svc.VAR}}`. |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "web",
  "kind": "app",
  "visibility": "public",
  "slug": "loja",
  "port": 3000,
  "source": {
    "type": "git",
    "repo": "acme/loja",
    "branch": "main"
  },
  "build": {
    "builder": "auto"
  },
  "healthcheck_path": "/health",
  "resources": {
    "memory_mb": 512,
    "cpus": 0.5
  },
  "auto_deploy": true,
  "needs_redeploy": false,
  "status": "running",
  "public_url": "https://loja.nebularapps.com",
  "depends_on": [
    "db"
  ],
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PATCH `/v1/projects/{p}/services/{s}`

Atualiza o serviço

Atualização parcial; o que for omitido não muda. Mudar configuração marca o serviço como `needs_redeploy`.

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `updateService`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `visibility` | enum(public, private) | não |  |
| `slug` | string | não |  |
| `source` | object | não |  |
| `source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `source.repo` | string | não | `git`: `dono/repositório`. |
| `source.branch` | string | não | `git`: branch implantada. |
| `source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `build` | object | não |  |
| `build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `port` | integer | não |  |
| `healthcheck_path` | string | não |  |
| `start_command` | string | não |  |
| `build_command` | string | não |  |
| `resources` | object | não |  |
| `resources.memory_mb` | integer | sim |  |
| `resources.cpus` | number | sim |  |
| `auto_deploy` | boolean | não |  |

### Resposta 200

Serviço atualizado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `name` | string | sim | Nome único no projeto (`^[a-z][a-z0-9-]{0,30}$`). |
| `kind` | enum(app, database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | não | Só `kind=database`. |
| `visibility` | enum(public, private) | sim |  |
| `slug` | string | não | Subdomínio público (`visibility=public`). |
| `port` | integer | sim |  |
| `source` | object | sim |  |
| `source.type` | enum(upload, git, image, database) | sim | De onde vem o código. |
| `source.repo` | string | não | `git`: `dono/repositório`. |
| `source.branch` | string | não | `git`: branch implantada. |
| `source.root_dir` | string | não | `git`: subdiretório do monorepo. |
| `source.watch_paths` | array<string> | não | `git`: globs que disparam deploy automático. |
| `source.ref` | string | não | `image`: `repo[:tag]@sha256:<digest>`. |
| `build` | object | sim |  |
| `build.builder` | enum(auto, node, go, rust, python, static, dockerfile, none) | sim | Como construir. |
| `healthcheck_path` | string | não |  |
| `start_command` | string | não |  |
| `build_command` | string | não |  |
| `resources` | object | sim |  |
| `resources.memory_mb` | integer | sim |  |
| `resources.cpus` | number | sim |  |
| `auto_deploy` | boolean | sim |  |
| `needs_redeploy` | boolean | sim | Variáveis ou configuração mudaram desde o último deploy. |
| `status` | enum(idle, deploying, running, failed) | sim | Derivado do deployment mais recente. |
| `public_url` | string | não |  |
| `depends_on` | array<string> | sim | Nomes dos serviços referenciados por `${{svc.VAR}}`. |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "web",
  "kind": "app",
  "visibility": "public",
  "slug": "loja",
  "port": 3000,
  "source": {
    "type": "git",
    "repo": "acme/loja",
    "branch": "main"
  },
  "build": {
    "builder": "auto"
  },
  "healthcheck_path": "/health",
  "resources": {
    "memory_mb": 512,
    "cpus": 0.5
  },
  "auto_deploy": true,
  "needs_redeploy": false,
  "status": "running",
  "public_url": "https://loja.nebularapps.com",
  "depends_on": [
    "db"
  ],
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`slug_taken`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/services/{s}`

Apaga o serviço

Apaga o serviço com deployments, variáveis e domínios. Serviço com **volume** exige apagar o volume antes (`409 volume_attached`). Idempotente (repetir ⇒ `204`).

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `deleteService`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Resposta 409

`volume_attached`: apague o volume primeiro.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/deploys.md

# Deploys (referência)

## POST `/v1/projects/{p}/deploy`

Deploy do projeto (grupo)

Implanta vários serviços em **ordem de dependência** (`${{svc.VAR}}`), em camadas: a camada N só começa quando a N-1 está `ready`; dependente de um que falhou fica `blocked`. `services` vazio ou omitido = todos os serviços de aplicação **que têm o que implantar**: o serviço sem fonte (p.ex. o `web` de um projeto novo, sem upload nem git/imagem) entra no grupo como item `skipped`, com `reason`, e não faz o grupo falhar; um grupo em que tudo é `skipped` termina `ready`. Listar o serviço em `services` não o pula: sem fonte, o deploy dele falha. Faça polling em `GET …/group-deployments/{g}`. Referências inexistentes ou em ciclo são recusadas antes de criar qualquer coisa (`422`). Conta um deployment por serviço no limite por hora do time (`429 rate_limited` + `Retry-After`).

Escopo exigido: `deploy`.

Escopo exigido: `deploy` · operationId: `deployGroup`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `services` | array<string> | não | Ids ou nomes (até 100); vazio ou omitido = todos os serviços de aplicação. |

### Resposta 202

Deploy de grupo aceito.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `status` | enum(running, ready, failed, canceled, superseded) | sim |  |
| `error` | string | não | Motivo, quando `failed`. |
| `items` | array<object> | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].deployment_id` | string | não | Ausente para itens `blocked` e `skipped`. |
| `items[].status` | enum(queued, building, deploying, ready, failed, blocked, canceled, skipped) | sim | Status do deployment do item, `blocked` (dependência falhou) ou `skipped` (serviço sem fonte para implantar; veja `reason`). |
| `items[].reason` | string | não | Motivo, presente só nos itens `skipped`. |
| `items[].layer` | integer | sim | Camada de dependência (0 = sem dependências). |

```json
{
  "id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "status": "running",
  "items": [
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
      "status": "ready",
      "layer": 0
    },
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a8k",
      "status": "building",
      "layer": 1
    }
  ]
}
```

### Resposta 422

`unresolved_reference`, `reference_cycle` ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "unresolved_reference",
  "message": "Há referências para variáveis ou serviços que não existem.",
  "details": {
    "references": [
      "db.MYSQL_HOST"
    ]
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/group-deployments/{g}`

Consulta um deploy de grupo (polling)

Estado do grupo e de cada serviço (`items`, com a `layer`).

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getGroupDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `g` | path | string | sim | Id do deploy de grupo. |

### Resposta 200

Grupo.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `status` | enum(running, ready, failed, canceled, superseded) | sim |  |
| `error` | string | não | Motivo, quando `failed`. |
| `items` | array<object> | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].deployment_id` | string | não | Ausente para itens `blocked` e `skipped`. |
| `items[].status` | enum(queued, building, deploying, ready, failed, blocked, canceled, skipped) | sim | Status do deployment do item, `blocked` (dependência falhou) ou `skipped` (serviço sem fonte para implantar; veja `reason`). |
| `items[].reason` | string | não | Motivo, presente só nos itens `skipped`. |
| `items[].layer` | integer | sim | Camada de dependência (0 = sem dependências). |

```json
{
  "id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "status": "running",
  "items": [
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
      "status": "ready",
      "layer": 0
    },
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a8k",
      "status": "building",
      "layer": 1
    }
  ]
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/group-deployments/{g}/cancel`

Cancela um deploy de grupo

Cancela o que ainda não terminou. Um grupo finalizado volta inalterado.

Escopo exigido: `deploy`.

Escopo exigido: `deploy` · operationId: `cancelGroupDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `g` | path | string | sim | Id do deploy de grupo. |

### Resposta 202

Grupo (cancelado ou inalterado).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `project_id` | string | sim |  |
| `status` | enum(running, ready, failed, canceled, superseded) | sim |  |
| `error` | string | não | Motivo, quando `failed`. |
| `items` | array<object> | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].deployment_id` | string | não | Ausente para itens `blocked` e `skipped`. |
| `items[].status` | enum(queued, building, deploying, ready, failed, blocked, canceled, skipped) | sim | Status do deployment do item, `blocked` (dependência falhou) ou `skipped` (serviço sem fonte para implantar; veja `reason`). |
| `items[].reason` | string | não | Motivo, presente só nos itens `skipped`. |
| `items[].layer` | integer | sim | Camada de dependência (0 = sem dependências). |

```json
{
  "id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "status": "running",
  "items": [
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
      "status": "ready",
      "layer": 0
    },
    {
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "deployment_id": "01jb7k5a5q8r7t2v4w6x8y0a8k",
      "status": "building",
      "layer": 1
    }
  ]
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/deployments`

Lista os deployments do serviço

Deployments do mais novo para o mais antigo.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listDeployments`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].group_deployment_id` | string | não |  |
| `items[].status` | enum(queued, building, deploying, ready, failed, blocked, canceled, superseded) | sim | `canceled` e `deploying` podem ainda aparecer como `failed`/`building` em instalações antigas. |
| `items[].trigger` | enum(api, git, dash, rollback, template, manual) | sim | Quem disparou. `manual` é o que o servidor devolve para disparos feitos pelo painel quando a origem não foi registrada. |
| `items[].source_ref` | string | não | SHA/branch (git) ou referência da imagem. |
| `items[].image_digest` | string | não |  |
| `items[].error` | object | não |  |
| `items[].error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `items[].error.message` | string | sim |  |
| `items[].error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `items[].created_at` | string | sim |  |
| `items[].started_at` | string | não |  |
| `items[].finished_at` | string | não |  |

```json
{
  "items": [
    {
      "id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "group_deployment_id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
      "status": "building",
      "trigger": "api",
      "source_ref": "main",
      "created_at": "2026-10-10T14:03:11Z",
      "started_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": "MDFqYjdrNWE1cThyN3QydjR3NnU4eTBhM2Q",
  "has_more": true
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services/{s}/deployments`

Dispara um deploy do serviço

Dispara um deployment do serviço e devolve `202` com o deployment (o trabalho é assíncrono: faça polling em `GET …/deployments/{d}`).
Corpo: `{}` (último commit da branch ou a imagem do serviço), `{"ref":"<sha|branch>"}` (git), `{"image":"repo@sha256:…"}` (imagem), ou **multipart** com o campo `file` (tar.gz ou zip, até 512 MB) para enviar o código-fonte.
Referências `${{svc.VAR}}` são validadas no disparo: inexistentes ou em ciclo ⇒ `422 unresolved_reference` / `reference_cycle` com `details.references`; se só aparecerem no build, ficam em `deployment.error`.

Estados: `queued → building → deploying → ready`, ou `failed` / `blocked` / `canceled` / `superseded`. Faça polling com backoff (comece em 2 s, dobre até 15 s). Não há webhooks neste ciclo.
**Limite por hora:** cada time pode criar no máximo N deployments (todos os projetos somados) em uma janela deslizante de 1 hora (`GET /v1/limits` → `deploys_per_hour`); acima disso, `429 rate_limited` com `Retry-After` (segundos até liberar uma vaga).
Imagem com `USER root` roda como `65534`; se o container encerrar nos primeiros 30 s depois de iniciar, o deployment falha com `error.code=image_requires_root` e a mensagem pede para declarar `build.user` (uid[:gid], nunca root) no serviço. Corpo ausente (sem `Content-Type`) vale `{}`; com corpo, é JSON (ou multipart). Armazenamento de builds da plataforma cheio ou indisponível ⇒ `503 unavailable` com `details.deployment_id` (um deployment `failed` fica no histórico com `error.code` `build_disk_full` ou `build_storage_unavailable`) e `details.error_code`; repita em alguns minutos.

Escopo exigido: `deploy`.

Escopo exigido: `deploy` · operationId: `createDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

### Corpo (multipart/form-data)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `file` | string | sim | Arquivo `.tar.gz` ou `.zip` com o código. |

### Resposta 202

Deployment aceito.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `group_deployment_id` | string | não |  |
| `status` | enum(queued, building, deploying, ready, failed, blocked, canceled, superseded) | sim | `canceled` e `deploying` podem ainda aparecer como `failed`/`building` em instalações antigas. |
| `trigger` | enum(api, git, dash, rollback, template, manual) | sim | Quem disparou. `manual` é o que o servidor devolve para disparos feitos pelo painel quando a origem não foi registrada. |
| `source_ref` | string | não | SHA/branch (git) ou referência da imagem. |
| `image_digest` | string | não |  |
| `error` | object | não |  |
| `error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `error.message` | string | sim |  |
| `error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `created_at` | string | sim |  |
| `started_at` | string | não |  |
| `finished_at` | string | não |  |

```json
{
  "id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "group_deployment_id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "status": "building",
  "trigger": "api",
  "source_ref": "main",
  "created_at": "2026-10-10T14:03:11Z",
  "started_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`deploy_in_progress`: já há um deploy em andamento neste serviço.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 413

Código-fonte (multipart) acima do limite.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`unresolved_reference`, `reference_cycle`, `invalid_reference`, `reference_too_deep`, `value_too_large` (com `details`) ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "unresolved_reference",
  "message": "Há referências para variáveis ou serviços que não existem.",
  "details": {
    "references": [
      "db.MYSQL_HOST"
    ]
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/deployments/{d}`

Consulta um deployment (polling)

Estado atual do deployment. Quando `failed`, `error` traz `code`, `message` e `details`.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do deployment (do serviço da rota). |

### Resposta 200

Deployment.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `group_deployment_id` | string | não |  |
| `status` | enum(queued, building, deploying, ready, failed, blocked, canceled, superseded) | sim | `canceled` e `deploying` podem ainda aparecer como `failed`/`building` em instalações antigas. |
| `trigger` | enum(api, git, dash, rollback, template, manual) | sim | Quem disparou. `manual` é o que o servidor devolve para disparos feitos pelo painel quando a origem não foi registrada. |
| `source_ref` | string | não | SHA/branch (git) ou referência da imagem. |
| `image_digest` | string | não |  |
| `error` | object | não |  |
| `error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `error.message` | string | sim |  |
| `error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `created_at` | string | sim |  |
| `started_at` | string | não |  |
| `finished_at` | string | não |  |

```json
{
  "id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "group_deployment_id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "status": "building",
  "trigger": "api",
  "source_ref": "main",
  "created_at": "2026-10-10T14:03:11Z",
  "started_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services/{s}/deployments/{d}/cancel`

Cancela um deployment

Cancela um deployment `queued`/`building`/`deploying`. Um deployment já terminado volta inalterado. Só cancela jobs enfileirados no processo atual (`409 not_cancelable` nos demais).

Escopo exigido: `deploy`.

Escopo exigido: `deploy` · operationId: `cancelDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do deployment (do serviço da rota). |

### Resposta 202

Deployment (cancelado ou inalterado).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `group_deployment_id` | string | não |  |
| `status` | enum(queued, building, deploying, ready, failed, blocked, canceled, superseded) | sim | `canceled` e `deploying` podem ainda aparecer como `failed`/`building` em instalações antigas. |
| `trigger` | enum(api, git, dash, rollback, template, manual) | sim | Quem disparou. `manual` é o que o servidor devolve para disparos feitos pelo painel quando a origem não foi registrada. |
| `source_ref` | string | não | SHA/branch (git) ou referência da imagem. |
| `image_digest` | string | não |  |
| `error` | object | não |  |
| `error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `error.message` | string | sim |  |
| `error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `created_at` | string | sim |  |
| `started_at` | string | não |  |
| `finished_at` | string | não |  |

```json
{
  "id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "group_deployment_id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "status": "building",
  "trigger": "api",
  "source_ref": "main",
  "created_at": "2026-10-10T14:03:11Z",
  "started_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`not_cancelable`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services/{s}/deployments/{d}/rollback`

Volta para um deployment anterior

Cria um **novo** deployment (`trigger=rollback`) que reimplanta `{d}` com as variáveis dele. Corpo: `{}` ou vazio. Conta no limite de deployments por hora do time (`429 rate_limited` + `Retry-After`).

Escopo exigido: `deploy`.

Escopo exigido: `deploy` · operationId: `rollbackDeployment`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do deployment (do serviço da rota). |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Resposta 202

Rollback aceito (novo deployment).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `group_deployment_id` | string | não |  |
| `status` | enum(queued, building, deploying, ready, failed, blocked, canceled, superseded) | sim | `canceled` e `deploying` podem ainda aparecer como `failed`/`building` em instalações antigas. |
| `trigger` | enum(api, git, dash, rollback, template, manual) | sim | Quem disparou. `manual` é o que o servidor devolve para disparos feitos pelo painel quando a origem não foi registrada. |
| `source_ref` | string | não | SHA/branch (git) ou referência da imagem. |
| `image_digest` | string | não |  |
| `error` | object | não |  |
| `error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `error.message` | string | sim |  |
| `error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `created_at` | string | sim |  |
| `started_at` | string | não |  |
| `finished_at` | string | não |  |

```json
{
  "id": "01jb7k5a5q8r7t2v4w6x8y0a3d",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "group_deployment_id": "01jb7k7a5q8r7t2v4w6x8y0a5f",
  "status": "building",
  "trigger": "api",
  "source_ref": "main",
  "created_at": "2026-10-10T14:03:11Z",
  "started_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`nothing_to_rollback` ou `deploy_in_progress`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/logs.md

# Logs (referência)

## GET `/v1/projects/{p}/services/{s}/logs`

Log de execução do serviço

Lê o log do container a partir de `since` (omitido = final do log) e `cursor`. Segredos são mascarados.

Escopo exigido: `logs:read`.

Escopo exigido: `logs:read` · operationId: `getRuntimeLogs`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `since` | query | string | não | Instante RFC 3339 a partir do qual ler o log de execução. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da leitura anterior. |

### Resposta 200

Trecho do log.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `text` | string | sim | Trecho de log (segredos mascarados). |
| `next_cursor` | string | sim | Passe em `cursor` para continuar; vazio = ainda sem mais dados. |
| `done` | boolean | sim | `true` quando não haverá mais log (build terminado). |

```json
{
  "text": "Step 1/5 : FROM node:22\n",
  "next_cursor": "MTI4",
  "done": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/deployments/{d}/logs`

Log de build do deployment

Lê o log de build a partir de `cursor` (vazio = início). Continue com `next_cursor` até `done=true`. Segredos são mascarados.

Escopo exigido: `logs:read`.

Escopo exigido: `logs:read` · operationId: `getBuildLogs`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do deployment (do serviço da rota). |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da leitura anterior. |

### Resposta 200

Trecho do log.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `text` | string | sim | Trecho de log (segredos mascarados). |
| `next_cursor` | string | sim | Passe em `cursor` para continuar; vazio = ainda sem mais dados. |
| `done` | boolean | sim | `true` quando não haverá mais log (build terminado). |

```json
{
  "text": "Step 1/5 : FROM node:22\n",
  "next_cursor": "MTI4",
  "done": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/variaveis.md

# Variáveis (referência)

## GET `/v1/projects/{p}/shared-variables`

Lista as variáveis compartilhadas do projeto (chegam a um serviço só por referência ${{shared.NOME}})

Ordenadas por nome. Valor de variável **sensível** vem `null` (com `sensitive=true`) a não ser que o token tenha `env:reveal`.

Escopo exigido: `env:read`. Com `env:reveal`: valores sensíveis em claro.

Escopo exigido: `env:read` · opcional (muda a resposta): `env:reveal` · operationId: `listSharedVariables`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].name` | string | sim |  |
| `items[].value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `items[].sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `items[].effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |

```json
{
  "items": [
    {
      "name": "LOG_LEVEL",
      "value": "info",
      "sensitive": false
    },
    {
      "name": "SESSION_SECRET",
      "value": null,
      "sensitive": true
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PUT `/v1/projects/{p}/shared-variables`

Grava várias variáveis compartilhadas do projeto (chegam a um serviço só por referência ${{shared.NOME}})

Cria ou substitui de 1 a 200 variáveis, **tudo ou nada**. A resposta mascara os sensíveis e lista em `needs_redeploy` os serviços que precisam de novo deploy.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `putManySharedVariables`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `variables` | array<object> | sim |  |
| `variables[].name` | string | sim |  |
| `variables[].value` | string | sim |  |
| `variables[].sensitive` | boolean | não |  |

### Resposta 200

Variáveis gravadas.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `items` | array<object> | sim |  |
| `items[].name` | string | sim |  |
| `items[].value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `items[].sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `items[].effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |
| `needs_redeploy` | array<string> | sim |  |

```json
{
  "items": [
    {
      "name": "LOG_LEVEL",
      "value": "info",
      "sensitive": false
    },
    {
      "name": "SESSION_SECRET",
      "value": null,
      "sensitive": true
    }
  ],
  "needs_redeploy": [
    "web"
  ]
}
```

### Resposta 409

`sensitive_lowered` (sensível não volta a não-sensível) ou `duplicate_variable`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de variáveis).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/shared-variables/{name}`

Lê uma variável

Valor sensível vem `null` sem `env:reveal`.

Escopo exigido: `env:read`. Com `env:reveal`: valor sensível em claro.

Escopo exigido: `env:read` · opcional (muda a resposta): `env:reveal` · operationId: `getSharedVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Resposta 200

Variável.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |

```json
{
  "name": "LOG_LEVEL",
  "value": "info",
  "sensitive": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PUT `/v1/projects/{p}/shared-variables/{name}`

Define uma variável

Cria ou substitui. **Nunca devolve** o valor de uma variável sensível. Referências `${{svc.VAR}}` são validadas na sintaxe.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `putSharedVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `value` | string | sim |  |
| `sensitive` | boolean | não | Omitido mantém o valor atual (novas: `false`). Sensível nunca volta a não-sensível (`409 sensitive_lowered`). |

### Resposta 200

Variável gravada.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |
| `needs_redeploy` | array<string> | sim | Serviços marcados para novo deploy. |

```json
{
  "name": "LOG_LEVEL",
  "value": "info",
  "sensitive": false,
  "needs_redeploy": [
    "web"
  ]
}
```

### Resposta 409

`sensitive_lowered`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de variáveis).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/shared-variables/{name}`

Apaga uma variável

Remove a variável e marca os serviços afetados para novo deploy.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `deleteSharedVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Resposta 204

Removida.

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/variables`

Lista as variáveis do serviço

Ordenadas por nome. Valor de variável **sensível** vem `null` (com `sensitive=true`) a não ser que o token tenha `env:reveal`. Com `resolved=true` devolve o ambiente final (referências expandidas, variáveis automáticas e de banco).

Escopo exigido: `env:read`. Com `env:reveal`: valores sensíveis em claro; `resolved=true` exige este escopo (`403` sem ele).

Escopo exigido: `env:read` · opcional (muda a resposta): `env:reveal` · operationId: `listServiceVariables`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |
| `resolved` | query | boolean | não | `true` devolve o ambiente final do serviço (referências expandidas, variáveis automáticas e de banco). Exige `env:reveal` (senão `403`). Só em variáveis de serviço. |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].name` | string | sim |  |
| `items[].value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `items[].sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `items[].effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |

```json
{
  "items": [
    {
      "name": "LOG_LEVEL",
      "value": "info",
      "sensitive": false
    },
    {
      "name": "SESSION_SECRET",
      "value": null,
      "sensitive": true
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Resposta 422

`resolved=true` com referências inválidas: `unresolved_reference`, `reference_cycle`, `invalid_reference`, `reference_too_deep` ou `value_too_large` (com `details`).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "unresolved_reference",
  "message": "Há referências para variáveis ou serviços que não existem.",
  "details": {
    "references": [
      "db.MYSQL_HOST"
    ]
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PUT `/v1/projects/{p}/services/{s}/variables`

Grava várias variáveis do serviço

Cria ou substitui de 1 a 200 variáveis, **tudo ou nada**. A resposta mascara os sensíveis e lista em `needs_redeploy` os serviços que precisam de novo deploy.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `putManyServiceVariables`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `variables` | array<object> | sim |  |
| `variables[].name` | string | sim |  |
| `variables[].value` | string | sim |  |
| `variables[].sensitive` | boolean | não |  |

### Resposta 200

Variáveis gravadas.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `items` | array<object> | sim |  |
| `items[].name` | string | sim |  |
| `items[].value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `items[].sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `items[].effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |
| `needs_redeploy` | array<string> | sim |  |

```json
{
  "items": [
    {
      "name": "LOG_LEVEL",
      "value": "info",
      "sensitive": false
    },
    {
      "name": "SESSION_SECRET",
      "value": null,
      "sensitive": true
    }
  ],
  "needs_redeploy": [
    "web"
  ]
}
```

### Resposta 409

`sensitive_lowered` (sensível não volta a não-sensível) ou `duplicate_variable`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de variáveis).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/variables/{name}`

Lê uma variável

Valor sensível vem `null` sem `env:reveal`.

Escopo exigido: `env:read`. Com `env:reveal`: valor sensível em claro.

Escopo exigido: `env:read` · opcional (muda a resposta): `env:reveal` · operationId: `getServiceVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Resposta 200

Variável.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |

```json
{
  "name": "LOG_LEVEL",
  "value": "info",
  "sensitive": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PUT `/v1/projects/{p}/services/{s}/variables/{name}`

Define uma variável

Cria ou substitui. **Nunca devolve** o valor de uma variável sensível. Referências `${{svc.VAR}}` são validadas na sintaxe.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `putServiceVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `value` | string | sim |  |
| `sensitive` | boolean | não | Omitido mantém o valor atual (novas: `false`). Sensível nunca volta a não-sensível (`409 sensitive_lowered`). |

### Resposta 200

Variável gravada.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `value` | string\|null | sim | `null` quando a variável é sensível e o token não tem `env:reveal`. |
| `sensitive` | boolean | sim | Flag declarado: o valor foi marcado como sensível. Governa o mascaramento do valor e a regra de nunca rebaixar. |
| `effective_sensitive` | boolean | não | `true` quando a variável é sensível **ou** o valor referencia (`${{svc.VAR}}`) uma variável sensível (p.ex. `${{db.DATABASE_URL}}`): o valor resolvido herda a sensibilidade. Sempre enviado. O flag `sensitive` não muda por herança (continua o que o usuário declarou); o texto da referência é devolvido como está, e o valor herdado só sai em `?resolved=true`, que exige `env:reveal`. Referência que não resolve ou variável compartilhada: igual a `sensitive`. |
| `needs_redeploy` | array<string> | sim | Serviços marcados para novo deploy. |

```json
{
  "name": "LOG_LEVEL",
  "value": "info",
  "sensitive": false,
  "needs_redeploy": [
    "web"
  ]
}
```

### Resposta 409

`sensitive_lowered`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de variáveis).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/services/{s}/variables/{name}`

Apaga uma variável

Remove a variável e marca os serviços afetados para novo deploy.

Escopo exigido: `env:write`.

Escopo exigido: `env:write` · operationId: `deleteServiceVariable`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `name` | path | string | sim | Nome da variável (`^[A-Za-z_][A-Za-z0-9_]{0,255}$`). |

### Resposta 204

Removida.

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/volumes.md

# Volumes (referência)

## GET `/v1/projects/{p}/services/{s}/volume`

Consulta o volume

`404` quando o serviço não tem volume.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getVolume`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Resposta 200

Volume.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `mount_path` | string | sim |  |
| `size_gb` | integer | sim |  |
| `state` | string | sim | Ciclo do volume (`staged`, `active`, `retired`, `orphaned`). |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7ka15q8r7t2v4w6x8y0a8i",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "mount_path": "/data",
  "size_gb": 5,
  "state": "active",
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PUT `/v1/projects/{p}/services/{s}/volume`

Anexa ou aumenta o volume

Cada serviço tem no máximo um volume persistente (1 a 50 GB). Se já existe, só pode **crescer**.

Escopo exigido: `volumes:write`.

Escopo exigido: `volumes:write` · operationId: `putVolume`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `mount_path` | string | sim | Caminho absoluto dentro do container. Subpastas de /app (ex.: /app/data) são aceitas e ficam graváveis; /app inteiro, /app/.next, /app/.next/cache, /tmp, /proc, /sys, /dev e /etc são recusados. |
| `size_gb` | integer | sim |  |

### Resposta 200

Volume.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `mount_path` | string | sim |  |
| `size_gb` | integer | sim |  |
| `state` | string | sim | Ciclo do volume (`staged`, `active`, `retired`, `orphaned`). |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7ka15q8r7t2v4w6x8y0a8i",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "mount_path": "/data",
  "size_gb": 5,
  "state": "active",
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`volume_exists` ou `volume_in_use` (pare o serviço primeiro).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (cota de volumes do time ou sem capacidade).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/services/{s}/volume`

Apaga o volume e seus dados

**Irreversível**: apaga os dados do volume. Idempotente (sem volume ⇒ `204`). No painel exige confirmação de identidade (step-up); com token, o escopo `volumes:write` é a autorização.

Escopo exigido: `volumes:write`.

Escopo exigido: `volumes:write` · operationId: `deleteVolume`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/bancos.md

# Bancos (referência)

## GET `/v1/projects/{p}/databases`

Lista os bancos do projeto

Bancos do projeto, do mais antigo para o mais novo (`size_mb` do estado armazenado).

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listDatabases`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim | Id do serviço `kind=database`. |
| `items[].project_id` | string | sim |  |
| `items[].name` | string | sim |  |
| `items[].kind` | enum(database) | sim |  |
| `items[].engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `items[].status` | enum(provisioning, ready, read_only, error, deleting, running, idle, deploying, failed) | sim | Estado da instância. |
| `items[].size_mb` | integer | sim |  |
| `items[].quota_mb` | integer | sim |  |
| `items[].read_only` | boolean | sim | `true` quando o banco passou da cota. |
| `items[].host` | string | sim | Host público do motor do banco, com URL própria por motor no nó (PostgreSQL `db01.pgsql.<domínio>`, MariaDB `db01.mariadb.<domínio>`, sqlite `<banco>.db01.sqlite.<domínio>`); é o host das variáveis `DATABASE_URL`/`PGHOST`/`MYSQL_HOST`/`LIBSQL_URL`. |
| `items[].port` | integer | sim |  |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
      "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
      "name": "db",
      "kind": "database",
      "engine": "postgres",
      "status": "ready",
      "size_mb": 42,
      "quota_mb": 1024,
      "read_only": false,
      "host": "db01.pgsql.nebularws.com",
      "port": 5432,
      "created_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/databases`

Cria um banco gerenciado

Cria um serviço `kind=database` e provisiona a instância (`postgres`, `mariadb` ou `sqlite`). As credenciais não vêm na resposta: apps do projeto as recebem como variáveis `${{db.VAR}}`; para vê-las use `POST …/credentials`.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `createDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `quota_mb` | integer | sim |  |

### Resposta 201

Banco criado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do serviço `kind=database`. |
| `project_id` | string | sim |  |
| `name` | string | sim |  |
| `kind` | enum(database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `status` | enum(provisioning, ready, read_only, error, deleting, running, idle, deploying, failed) | sim | Estado da instância. |
| `size_mb` | integer | sim |  |
| `quota_mb` | integer | sim |  |
| `read_only` | boolean | sim | `true` quando o banco passou da cota. |
| `host` | string | sim | Host público do motor do banco, com URL própria por motor no nó (PostgreSQL `db01.pgsql.<domínio>`, MariaDB `db01.mariadb.<domínio>`, sqlite `<banco>.db01.sqlite.<domínio>`); é o host das variáveis `DATABASE_URL`/`PGHOST`/`MYSQL_HOST`/`LIBSQL_URL`. |
| `port` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "db",
  "kind": "database",
  "engine": "postgres",
  "status": "ready",
  "size_mb": 42,
  "quota_mb": 1024,
  "read_only": false,
  "host": "db01.pgsql.nebularws.com",
  "port": 5432,
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 409

`name_taken`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "name_taken",
  "message": "Já existe um serviço com esse nome no projeto."
}
```

### Resposta 422

`quota_exceeded` ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/databases/{s}`

Consulta um banco

Estado, tamanho e cota.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |

### Resposta 200

Banco.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do serviço `kind=database`. |
| `project_id` | string | sim |  |
| `name` | string | sim |  |
| `kind` | enum(database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `status` | enum(provisioning, ready, read_only, error, deleting, running, idle, deploying, failed) | sim | Estado da instância. |
| `size_mb` | integer | sim |  |
| `quota_mb` | integer | sim |  |
| `read_only` | boolean | sim | `true` quando o banco passou da cota. |
| `host` | string | sim | Host público do motor do banco, com URL própria por motor no nó (PostgreSQL `db01.pgsql.<domínio>`, MariaDB `db01.mariadb.<domínio>`, sqlite `<banco>.db01.sqlite.<domínio>`); é o host das variáveis `DATABASE_URL`/`PGHOST`/`MYSQL_HOST`/`LIBSQL_URL`. |
| `port` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "db",
  "kind": "database",
  "engine": "postgres",
  "status": "ready",
  "size_mb": 42,
  "quota_mb": 1024,
  "read_only": false,
  "host": "db01.pgsql.nebularws.com",
  "port": 5432,
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PATCH `/v1/projects/{p}/databases/{s}`

Altera a cota

Altera `quota_mb`.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `updateDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `quota_mb` | integer | sim |  |

### Resposta 200

Banco atualizado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do serviço `kind=database`. |
| `project_id` | string | sim |  |
| `name` | string | sim |  |
| `kind` | enum(database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `status` | enum(provisioning, ready, read_only, error, deleting, running, idle, deploying, failed) | sim | Estado da instância. |
| `size_mb` | integer | sim |  |
| `quota_mb` | integer | sim |  |
| `read_only` | boolean | sim | `true` quando o banco passou da cota. |
| `host` | string | sim | Host público do motor do banco, com URL própria por motor no nó (PostgreSQL `db01.pgsql.<domínio>`, MariaDB `db01.mariadb.<domínio>`, sqlite `<banco>.db01.sqlite.<domínio>`); é o host das variáveis `DATABASE_URL`/`PGHOST`/`MYSQL_HOST`/`LIBSQL_URL`. |
| `port` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "db",
  "kind": "database",
  "engine": "postgres",
  "status": "ready",
  "size_mb": 42,
  "quota_mb": 1024,
  "read_only": false,
  "host": "db01.pgsql.nebularws.com",
  "port": 5432,
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 422

`quota_exceeded`: a cota não comporta a operação.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/databases/{s}`

Apaga o banco

Apaga o banco. Corpo opcional `{"final_backup": true|false}` (padrão **true**: faz um backup antes). Idempotente: repetir para um banco que este time apagou pela API devolve `204`.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `deleteDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `final_backup` | boolean | não | Faz um backup antes de apagar (padrão `true`). |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/databases/{s}/backups`

Lista os backups

Backups do mais novo para o mais antigo.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listBackups`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].at` | string | sim |  |
| `items[].size` | integer | sim | Bytes. |
| `items[].status` | string | sim | Estado do backup (ex.: `done`). |

```json
{
  "items": [
    {
      "id": "01jb7kb15q8r7t2v4w6x8y0a1j",
      "at": "2026-10-10T14:03:11Z",
      "size": 44040192,
      "status": "done"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/databases/{s}/backups`

Inicia um backup

Backup sob demanda, assíncrono: acompanhe em `GET …/jobs/{job_id}`.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `createBackup`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Resposta 202

Backup iniciado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `job_id` | string | sim |  |
| `backup_id` | string | não | Só no backup. |

```json
{
  "job_id": "01jb7k8a5q8r7t2v4w6x8y0a6g",
  "backup_id": "01jb7kb15q8r7t2v4w6x8y0a1j"
}
```

### Resposta 422

`idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/databases/{s}/credentials`

Revela as credenciais de conexão

Devolve as credenciais em claro. **Nunca em `GET`**, nunca em cache, e a leitura é auditada. O token precisa do escopo `env:reveal` e ter sido criado com confirmação de identidade (step-up); sem isso, `403`.

Escopo exigido: `env:reveal`.

Escopo exigido: `env:reveal` · operationId: `revealDatabaseCredentials`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |

### Resposta 200

Credenciais.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `credentials` | array<object> | sim |  |
| `credentials[].name` | string | sim |  |
| `credentials[].value` | string | sim |  |

```json
{
  "credentials": [
    {
      "name": "DB_HOST",
      "value": "db"
    },
    {
      "name": "DB_PASSWORD",
      "value": "valor-exibido-uma-vez"
    }
  ]
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/databases/{s}/restore`

Restaura um backup

Inicia um restore. `target=new` (padrão) cria um banco **ao lado** do atual, sem substituí-lo: o serviço continua apontando para o banco de origem e o novo aparece em `GET …/restores` já com `status: restoring`. `same` **sobrescreve os dados vivos** (no painel exige step-up). Acompanhe em `GET …/jobs/{job_id}` ou em `GET …/restores`.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `restoreDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `backup_id` | string | sim |  |
| `target` | enum(new, same) | não | `new` (padrão) cria ao lado, sem substituir o banco atual; `same` sobrescreve o banco vivo (no painel exige step-up). |
| `new_db_name` | string | não | Ignorado: o nome do banco restaurado é gerado pelo servidor (`n_…`) e vem em `db_name` de `GET …/restores`. |

### Resposta 202

Restore iniciado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `job_id` | string | sim |  |
| `backup_id` | string | não | Só no backup. |

```json
{
  "job_id": "01jb7kc15q8r7t2v4w6x8y0a2k"
}
```

### Resposta 409

`backup_not_ready`: o backup ainda não terminou.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/databases/{s}/restores`

Lista os bancos criados por restore

Bancos criados por restores `target=new` ao lado do banco, de **qualquer motor**, com o estado de cada um (`restoring`, `ready` ou `failed`, com `error` quando falhou). Postgres e MariaDB: o banco restaurado (`db_name`) fica na mesma instância, host e porta, e usa as **mesmas credenciais** do banco de origem. SQLite: nasce uma instância própria (`url`; gere um token novo com a rotação).

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listRestores`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].job_id` | string | sim |  |
| `items[].backup_id` | string | sim |  |
| `items[].db_name` | string | sim | Nome do banco restaurado (postgres/mariadb: na mesma instância da origem; sqlite: o id da instância nova). |
| `items[].status` | enum(restoring, ready, failed) | sim | `restoring` enquanto o job roda; `ready` quando pronto para uso; `failed` com `error`. |
| `items[].error` | object | não |  |
| `items[].error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `items[].error.message` | string | sim |  |
| `items[].error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `items[].host` | string | sim |  |
| `items[].port` | integer | sim |  |
| `items[].url` | string | não | Só sqlite. |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7k9a5q8r7t2v4w6x8y0a7h",
      "job_id": "01jb7kc15q8r7t2v4w6x8y0a2k",
      "backup_id": "01jb7kb15q8r7t2v4w6x8y0a1j",
      "db_name": "n_k7p2m4q6r8t2v4w6",
      "status": "ready",
      "host": "db01.pgsql.example.com",
      "port": 5432,
      "created_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/databases/{s}/rotate`

Rotaciona as credenciais

Gera novas credenciais e marca os serviços dependentes para novo deploy.

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `rotateDatabase`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |

### Resposta 200

Banco.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim | Id do serviço `kind=database`. |
| `project_id` | string | sim |  |
| `name` | string | sim |  |
| `kind` | enum(database) | sim |  |
| `engine` | enum(postgres, mariadb, sqlite) | sim |  |
| `status` | enum(provisioning, ready, read_only, error, deleting, running, idle, deploying, failed) | sim | Estado da instância. |
| `size_mb` | integer | sim |  |
| `quota_mb` | integer | sim |  |
| `read_only` | boolean | sim | `true` quando o banco passou da cota. |
| `host` | string | sim | Host público do motor do banco, com URL própria por motor no nó (PostgreSQL `db01.pgsql.<domínio>`, MariaDB `db01.mariadb.<domínio>`, sqlite `<banco>.db01.sqlite.<domínio>`); é o host das variáveis `DATABASE_URL`/`PGHOST`/`MYSQL_HOST`/`LIBSQL_URL`. |
| `port` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "name": "db",
  "kind": "database",
  "engine": "postgres",
  "status": "ready",
  "size_mb": 42,
  "quota_mb": 1024,
  "read_only": false,
  "host": "db01.pgsql.nebularws.com",
  "port": 5432,
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/databases/{s}/jobs/{j}`

Consulta um job de backup/restore (polling)

`queued → running → done|failed`. Em restore `target=new`, `new_instance` descreve o banco criado ao lado e seu estado (sem credencial). Em job com falha, `error.code` é estável (`backup_failed`, `backup_tls_failed`, `restore_failed`, …) e `error.message` está em português claro, sem segredos.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getDatabaseJob`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `j` | path | string | sim | Id do job de backup/restore (`job_id`). |

### Resposta 200

Job.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `kind` | enum(backup, restore) | sim |  |
| `status` | enum(queued, running, done, failed) | sim |  |
| `error` | object | não |  |
| `error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `error.message` | string | sim |  |
| `error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `result` | any | não | Resultado do job quando `done` (qualquer JSON). |
| `new_instance` | object | não | Banco criado por um restore `target=new` (qualquer motor). Nunca carrega credencial (postgres/mariadb usam as da origem). |
| `new_instance.id` | string | sim |  |
| `new_instance.job_id` | string | sim |  |
| `new_instance.backup_id` | string | sim |  |
| `new_instance.db_name` | string | sim | Nome do banco restaurado (postgres/mariadb: na mesma instância da origem; sqlite: o id da instância nova). |
| `new_instance.status` | enum(restoring, ready, failed) | sim | `restoring` enquanto o job roda; `ready` quando pronto para uso; `failed` com `error`. |
| `new_instance.error` | object | não |  |
| `new_instance.error.code` | string | sim | Código estável da falha: `deploy_failed` (genérico), `unresolved_reference`, `reference_cycle`, `image_requires_root`, `crashed_after_start` e os do build: `build_clone_failed`, `build_detect_failed`, `build_install_failed`, `build_script_failed`, `build_copy_failed`, `build_activate_failed`, `activate_readonly_write` (o app tentou gravar sob `/app`, somente leitura: use um volume nessa pasta ou `/tmp`), `activate_app_crashed` (o app encerrou logo ao iniciar; a mensagem traz a primeira linha de erro do log), `activate_oom` (o app usou mais memória que o limite do serviço e foi encerrado), `activate_no_http` (o app estável e rodando não respondeu na porta esperada), `team_app_limit` (o time já roda o máximo de apps do plano; a mensagem traz N de M: pare ou remova um app, ou peça ao operador para ampliar o limite), `build_volume_unavailable`, `build_oom`, `build_timeout`, `build_storage_error` (falha interna de armazenamento da plataforma, não do repositório), `build_disk_full` (espaço de build cheio) e `build_storage_unavailable` (nenhum armazenamento de build utilizável na plataforma; não é falta de espaço). O código vem gravado com o deploy; `message` traz a causa em português (sem segredos nem caminhos do servidor). |
| `new_instance.error.message` | string | sim |  |
| `new_instance.error.details` | any | não | Dados extras do erro (qualquer JSON). |
| `new_instance.host` | string | sim |  |
| `new_instance.port` | integer | sim |  |
| `new_instance.url` | string | não | Só sqlite. |
| `new_instance.created_at` | string | sim |  |

```json
{
  "id": "01jb7k8a5q8r7t2v4w6x8y0a6g",
  "kind": "backup",
  "status": "done",
  "result": {
    "size": 44040192
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/databases/{s}/restores/{r}`

Apaga um banco de restore

Idempotente (repetir ⇒ `204`). Em postgres/mariadb o banco restaurado vive na instância da origem e só sai com ela: a resposta é `409 restore_not_removable`, exceto para um restore `failed` (só o registro é removido).

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `deleteRestore`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço `kind=database`. Serviço que não é banco ⇒ `404`. |
| `r` | path | string | sim | Id da instância criada por um restore `target=new`. |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Resposta 409

`restore_not_removable`: o banco restaurado divide a instância da origem e ainda não pode ser removido sozinho.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/dominios.md

# Domínios (referência)

## GET `/v1/projects/{p}/services/{s}/domains`

Lista os domínios do serviço

Domínios próprios anexados ao serviço, com o estado de verificação.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listDomains`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].hostname` | string | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].status` | enum(pending_dns, verifying, active, error) | sim |  |
| `items[].dns` | object | sim |  |
| `items[].dns.type` | string | sim |  |
| `items[].dns.name` | string | sim |  |
| `items[].dns.value` | string | sim |  |
| `items[].verification` | object | sim |  |
| `items[].verification.type` | string | sim |  |
| `items[].verification.name` | string | sim |  |
| `items[].verification.value` | string | sim |  |
| `items[].error` | string | não | Motivo (`misconfigured`, `conflict`, `txt_missing`, `wrong_target`, `dns_error`…). |
| `items[].redirect_to` | string | não |  |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7k6a5q8r7t2v4w6x8y0a4e",
      "hostname": "www.exemplo.test",
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "status": "pending_dns",
      "dns": {
        "type": "CNAME",
        "name": "www.exemplo.test",
        "value": "loja.nebularapps.com"
      },
      "verification": {
        "type": "TXT",
        "name": "_nebular-challenge.www.exemplo.test",
        "value": "nebular-verify=8f2c1d"
      },
      "created_at": "2026-10-10T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services/{s}/domains`

Anexa um domínio

Cria o domínio em `pending_dns` e devolve as instruções: o registro `dns` (CNAME/A) apontando para a plataforma e o `verification` TXT que prova a posse. Crie os dois no seu DNS e consulte o domínio até `active`.

Só serviços **públicos** (`visibility=public`) aceitam domínio: num serviço privado a resposta é `400 invalid_request`.

Se o hostname já é de um domínio **deste mesmo projeto que ficou sem site** (o serviço dele foi apagado; fica em revisão), ele é **religado** a este serviço em vez de responder `409 domain_taken`. Hostname de outro projeto ou de um domínio ligado a outro site continua `409`.

Escopo exigido: `domains:write`.

Escopo exigido: `domains:write` · operationId: `createDomain`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `hostname` | string | sim |  |
| `redirect_to` | string | não | Hostname para o qual redirecionar. |

### Resposta 201

Domínio criado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `hostname` | string | sim |  |
| `service_id` | string | sim |  |
| `status` | enum(pending_dns, verifying, active, error) | sim |  |
| `dns` | object | sim |  |
| `dns.type` | string | sim |  |
| `dns.name` | string | sim |  |
| `dns.value` | string | sim |  |
| `verification` | object | sim |  |
| `verification.type` | string | sim |  |
| `verification.name` | string | sim |  |
| `verification.value` | string | sim |  |
| `error` | string | não | Motivo (`misconfigured`, `conflict`, `txt_missing`, `wrong_target`, `dns_error`…). |
| `redirect_to` | string | não |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k6a5q8r7t2v4w6x8y0a4e",
  "hostname": "www.exemplo.test",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "status": "pending_dns",
  "dns": {
    "type": "CNAME",
    "name": "www.exemplo.test",
    "value": "loja.nebularapps.com"
  },
  "verification": {
    "type": "TXT",
    "name": "_nebular-challenge.www.exemplo.test",
    "value": "nebular-verify=8f2c1d"
  },
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 400

`invalid_request`: hostname ausente/inválido, ou o serviço não é público (`visibility=private` não aceita domínio).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "invalid_request",
  "message": "Só serviços públicos aceitam domínio."
}
```

### Resposta 409

`domain_taken`: o hostname já está em uso (por outro projeto ou por um domínio ligado a outro site).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de domínios do projeto) ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/projects/{p}/services/{s}/domains/{d}`

Consulta um domínio

Estado (`pending_dns`, `verifying`, `active`, `error`) e as instruções de DNS e de verificação.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `getDomain`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do domínio (do serviço da rota). |

### Resposta 200

Domínio.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `hostname` | string | sim |  |
| `service_id` | string | sim |  |
| `status` | enum(pending_dns, verifying, active, error) | sim |  |
| `dns` | object | sim |  |
| `dns.type` | string | sim |  |
| `dns.name` | string | sim |  |
| `dns.value` | string | sim |  |
| `verification` | object | sim |  |
| `verification.type` | string | sim |  |
| `verification.name` | string | sim |  |
| `verification.value` | string | sim |  |
| `error` | string | não | Motivo (`misconfigured`, `conflict`, `txt_missing`, `wrong_target`, `dns_error`…). |
| `redirect_to` | string | não |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k6a5q8r7t2v4w6x8y0a4e",
  "hostname": "www.exemplo.test",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "status": "pending_dns",
  "dns": {
    "type": "CNAME",
    "name": "www.exemplo.test",
    "value": "loja.nebularapps.com"
  },
  "verification": {
    "type": "TXT",
    "name": "_nebular-challenge.www.exemplo.test",
    "value": "nebular-verify=8f2c1d"
  },
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/projects/{p}/services/{s}/domains/{d}`

Remove um domínio

Desanexa o domínio. Idempotente: repetir para um domínio que este time removeu pela API devolve `204`.

Escopo exigido: `domains:write`.

Escopo exigido: `domains:write` · operationId: `deleteDomain`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do domínio (do serviço da rota). |

### Resposta 204

Removido (ou já removido anteriormente: repetir é `204`).

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## PATCH `/v1/projects/{p}/services/{s}/domains/{d}`

Define ou remove o redirecionamento do domínio

Faz o domínio redirecionar (301) para outro domínio **verificado do mesmo serviço** (`redirect_to` = id desse domínio) ou para de redirecionar (`redirect_to: null`). O campo é obrigatório: ausente ou vazio é `400 invalid_request`.

Escopo exigido: `domains:write`.

Escopo exigido: `domains:write` · operationId: `updateDomain`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do domínio (do serviço da rota). |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `redirect_to` | string\|null | sim | Id de outro domínio verificado deste serviço para redirecionar (301), ou `null` para parar de redirecionar. |

### Resposta 200

Domínio atualizado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `hostname` | string | sim |  |
| `service_id` | string | sim |  |
| `status` | enum(pending_dns, verifying, active, error) | sim |  |
| `dns` | object | sim |  |
| `dns.type` | string | sim |  |
| `dns.name` | string | sim |  |
| `dns.value` | string | sim |  |
| `verification` | object | sim |  |
| `verification.type` | string | sim |  |
| `verification.name` | string | sim |  |
| `verification.value` | string | sim |  |
| `error` | string | não | Motivo (`misconfigured`, `conflict`, `txt_missing`, `wrong_target`, `dns_error`…). |
| `redirect_to` | string | não |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k6a5q8r7t2v4w6x8y0a4e",
  "hostname": "www.exemplo.test",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "status": "pending_dns",
  "dns": {
    "type": "CNAME",
    "name": "www.exemplo.test",
    "value": "loja.nebularapps.com"
  },
  "verification": {
    "type": "TXT",
    "name": "_nebular-challenge.www.exemplo.test",
    "value": "nebular-verify=8f2c1d"
  },
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 400

`invalid_request`: `redirect_to` ausente, vazio ou de outro tipo, ou o alvo não é um domínio verificado deste serviço.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/services/{s}/domains/{d}/verify`

Verifica o domínio agora

Roda na hora a checagem de DNS e do TXT de posse (sem corpo) e devolve o domínio com o estado novo. Há um intervalo mínimo entre verificações manuais do mesmo domínio: antes dele a resposta é `422 rate_limited` com `details.retry_after_seconds`.

Escopo exigido: `domains:write`.

Escopo exigido: `domains:write` · operationId: `verifyDomain`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `s` | path | string | sim | Id ou nome do serviço dentro do projeto. |
| `d` | path | string | sim | Id do domínio (do serviço da rota). |

### Resposta 200

Domínio após a verificação.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `hostname` | string | sim |  |
| `service_id` | string | sim |  |
| `status` | enum(pending_dns, verifying, active, error) | sim |  |
| `dns` | object | sim |  |
| `dns.type` | string | sim |  |
| `dns.name` | string | sim |  |
| `dns.value` | string | sim |  |
| `verification` | object | sim |  |
| `verification.type` | string | sim |  |
| `verification.name` | string | sim |  |
| `verification.value` | string | sim |  |
| `error` | string | não | Motivo (`misconfigured`, `conflict`, `txt_missing`, `wrong_target`, `dns_error`…). |
| `redirect_to` | string | não |  |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7k6a5q8r7t2v4w6x8y0a4e",
  "hostname": "www.exemplo.test",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "status": "pending_dns",
  "dns": {
    "type": "CNAME",
    "name": "www.exemplo.test",
    "value": "loja.nebularapps.com"
  },
  "verification": {
    "type": "TXT",
    "name": "_nebular-challenge.www.exemplo.test",
    "value": "nebular-verify=8f2c1d"
  },
  "created_at": "2026-10-10T14:03:11Z"
}
```

### Resposta 422

`rate_limited`: verificação manual recente; tente de novo após `details.retry_after_seconds`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "rate_limited",
  "message": "Aguarde alguns segundos para verificar de novo.",
  "details": {
    "retry_after_seconds": 7
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/templates.md

# Templates (referência)

## GET `/v1/templates`

Catálogo de templates

Templates disponíveis, ordenados por id. Cada um traz os `params` aceitos e sua versão.

Escopo exigido: `templates:deploy`.

Escopo exigido: `templates:deploy` · operationId: `listTemplates`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página (mais novo/antigo primeiro conforme o recurso).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].name` | string | sim |  |
| `items[].version` | integer | sim |  |
| `items[].params` | array<object> | sim |  |
| `items[].params[].name` | string | sim |  |
| `items[].params[].type` | string | sim |  |
| `items[].params[].default` | any | não | Valor padrão (qualquer JSON). |

```json
{
  "items": [
    {
      "id": "wordpress",
      "name": "WordPress",
      "version": 1,
      "params": [
        {
          "name": "table_prefix",
          "type": "string",
          "default": "wp_"
        }
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/projects/{p}/templates/{t}`

Instancia um template no projeto

Cria **atomicamente** os serviços do template (falhou ⇒ desfaz o que criou) e inicia o deploy de grupo dos apps (`deploy_started`). Se o deploy não pôde iniciar, `deploy_error` diz por quê e os serviços continuam criados. Idempotente pela `Idempotency-Key`. O serviço `web` que todo projeto traz é **adotado** pelo template que declara um `web`, se ainda estiver virgem (sem deploy, variáveis, domínio ou volume); qualquer outro nome já em uso, ou um `web` já usado, ⇒ `409 name_taken`. Sem bancos ou volumes habilitados na instalação ⇒ `503`.

Escopo exigido: `templates:deploy`.

Escopo exigido: `templates:deploy` · operationId: `instantiateTemplate`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `t` | path | string | sim | Id do template (`GET /v1/templates`). |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. |

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `params` | object | não | Valores dos parâmetros do template: texto, número ou booleano. |

### Resposta 201

Template instanciado.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `template_id` | string | sim |  |
| `version` | integer | sim |  |
| `project_id` | string | sim |  |
| `services` | array<object> | sim |  |
| `services[].id` | string | sim |  |
| `services[].name` | string | sim |  |
| `services[].kind` | enum(app, database) | sim |  |
| `deploy_started` | boolean | sim | O deploy de grupo dos apps foi iniciado. |
| `deploy_error` | string | não | Por que o deploy não iniciou (os serviços continuam criados). Consulte `group-deployments`. |

```json
{
  "template_id": "wordpress",
  "version": 1,
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "services": [
    {
      "id": "01jb7k4a5q8r7t2v4w6x8y0a9z",
      "name": "db",
      "kind": "database"
    },
    {
      "id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "name": "web",
      "kind": "app"
    }
  ],
  "deploy_started": true
}
```

### Resposta 409

`name_taken`: já existe serviço com o nome de um serviço do template.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "name_taken",
  "message": "Já existe um serviço com esse nome no projeto."
}
```

### Resposta 422

`quota_exceeded` ou `idempotency_conflict`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `413` Corpo JSON acima do limite da rota (`too_large`); `415` O corpo precisa ser `application/json` (`unsupported_media_type`); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/arquivos.md

# Galerias e arquivos (referência)

## GET `/v1/galleries`

Lista as galerias visíveis ao token

Retorna as galerias do time do token (ou apenas as permitidas, se o token for restrito).
Escopo exigido: `assets:read`.

Escopo exigido: `assets:read` · operationId: `listGalleries`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `project` | query | string | não | Filtra por id de projeto. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |

### Resposta 200

Página de galerias.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].key` | string | sim | Chave pública imutável usada nas URLs. |
| `items[].name` | string | sim |  |
| `items[].bucket` | object | sim |  |
| `items[].bucket.id` | string | sim |  |
| `items[].bucket.label` | string | sim | Rótulo do host. |
| `items[].bucket.kind` | enum(shared, dedicated) | sim |  |
| `items[].bucket.host` | string | sim |  |
| `items[].project` | object \| null | sim |  |
| `items[].assets_count` | integer | sim |  |
| `items[].bytes` | integer | sim |  |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "gal_01J9ZK5Q",
      "key": "marcas-k7p2",
      "name": "Marcas",
      "bucket": {
        "id": "bkt_01J9ZG00",
        "label": "media",
        "kind": "shared",
        "host": "media.nebularcdn.com"
      },
      "project": {
        "id": "prj_01J9ZK3M",
        "name": "Site Acme",
        "slug": "site-acme"
      },
      "assets_count": 12,
      "bytes": 4823910,
      "created_at": "2026-10-09T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/galleries`

Cria uma galeria

Cria a galeria no bucket padrão do time. A `key` pública é gerada pelo servidor e é imutável.
Escopo exigido: `galleries:manage`. Um token **restrito a galerias específicas** não pode criar
galerias (a nova ficaria fora da lista dele): recebe `403 forbidden`.

Escopo exigido: `galleries:manage` · operationId: `createGallery`

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `project_id` | string | não | Projeto ao qual a galeria será associada (organização apenas). |

```json
{
  "name": "Marcas",
  "project_id": "prj_01J9ZK3M"
}
```

### Resposta 201

Galeria criada.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `key` | string | sim | Chave pública imutável usada nas URLs. |
| `name` | string | sim |  |
| `bucket` | object | sim |  |
| `bucket.id` | string | sim |  |
| `bucket.label` | string | sim | Rótulo do host. |
| `bucket.kind` | enum(shared, dedicated) | sim |  |
| `bucket.host` | string | sim |  |
| `project` | object \| null | sim |  |
| `assets_count` | integer | sim |  |
| `bytes` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "gal_01J9ZK5Q",
  "key": "marcas-k7p2",
  "name": "Marcas",
  "bucket": {
    "id": "bkt_01J9ZG00",
    "label": "media",
    "kind": "shared",
    "host": "media.nebularcdn.com"
  },
  "project": {
    "id": "prj_01J9ZK3M",
    "name": "Site Acme",
    "slug": "site-acme"
  },
  "assets_count": 0,
  "bytes": 0,
  "created_at": "2026-10-09T14:03:11Z"
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/galleries/{key}/assets`

Lista os arquivos de uma galeria

Lista arquivos com URLs e status de varredura. Escopo exigido: `assets:read`.

Escopo exigido: `assets:read` · operationId: `listAssets`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `key` | path | string | sim | Chave pública imutável da galeria (ex.: `marcas-k7p2`). |
| `prefix` | query | string | não | Retorna apenas nomes que começam com este prefixo. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |

### Resposta 200

Página de arquivos.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].name` | string | sim |  |
| `items[].gallery_key` | string | sim |  |
| `items[].current` | object | sim |  |
| `items[].current.id` | string | sim |  |
| `items[].current.hash` | string | sim | SHA-256 hexadecimal do conteúdo. |
| `items[].current.bytes` | integer | sim |  |
| `items[].current.content_type` | string | sim | Detectado pelo conteúdo. |
| `items[].current.class` | enum(image, svg, font, media, document, markup, archive, binary) | sim | Classe do arquivo, detectada pelo conteúdo. Define como a CDN serve o arquivo (ver descrição geral). |
| `items[].current.width` | integer\|null | sim | Somente imagens. |
| `items[].current.height` | integer\|null | sim | Somente imagens. |
| `items[].current.variants` | array<string> | sim | Larguras de variantes geradas (imagens). |
| `items[].current.scan` | object | sim |  |
| `items[].current.scan.status` | enum(pending, clean, rejected, quarantined) | sim | `pending`: aguardando varredura, não publicado. `clean`: publicado. `rejected`: recusado. `quarantined`: detectado na varredura diária; deixou de ser servido (451). |
| `items[].current.scan.reason` | string\|null | sim | Motivo da recusa ou quarentena. |
| `items[].current.scan.engine` | string\|null | sim |  |
| `items[].current.scan.scanned_at` | string\|null | sim |  |
| `items[].current.url` | string\|null | sim | URL **imutável** (`https://<bucket>.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`), com `Cache-Control: public, max-age=31536000, immutable`; `null` enquanto o arquivo não estiver `clean`. Para imagens aceita `?w=640` (largura) e `?q=` (qualidade); o formato (AVIF/WebP) é negociado por `Accept` com `Vary: Accept`. Se a segregação de downloads estiver ligada, classes de download usam outro domínio; use sempre a URL devolvida pela API, sem montá-la. |
| `items[].current.uploaded_by` | object | sim |  |
| `items[].current.uploaded_by.kind` | enum(user, token) | sim |  |
| `items[].current.uploaded_by.name` | string | sim |  |
| `items[].current.created_at` | string | sim |  |
| `items[].alias_url` | string\|null | sim | URL **alias** (`https://<bucket>.nebularcdn.com/<gallery_key>/<name>`), sempre a versão atual (`max-age=60, stale-while-revalidate=86400`); `null` enquanto não `clean`. Também aceita `?w=640`, ex.: `https://media.nebularcdn.com/marcas-k7p2/logos/acme.png?w=640`. |
| `items[].versions_count` | integer | sim |  |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "ast_01J9ZK8W",
      "name": "logos/acme.png",
      "gallery_key": "marcas-k7p2",
      "current": {
        "id": "ver_01J9ZK8X",
        "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "bytes": 48213,
        "content_type": "image/png",
        "class": "image",
        "width": 1200,
        "height": 630,
        "variants": [
          "320",
          "640",
          "1280"
        ],
        "scan": {
          "status": "clean",
          "reason": null,
          "engine": "clamav",
          "scanned_at": "2026-10-09T14:05:02Z"
        },
        "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
        "uploaded_by": {
          "kind": "token",
          "name": "agente-deploy"
        },
        "created_at": "2026-10-09T14:05:01Z"
      },
      "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
      "versions_count": 1,
      "created_at": "2026-10-09T14:05:01Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## POST `/v1/galleries/{key}/assets`

Envia ou versiona um arquivo

Envia um arquivo (multipart). Se o nome já existir, cria uma nova versão; o alias passa a apontar
para ela. Escopo exigido: `assets:write`.

- **201**: varredura concluída e arquivo `clean` — já está publicado.
- **202**: o arquivo está `pending` (scanner ocupado ou fora do ar) e **não foi publicado**. Consulte
  `GET /v1/galleries/{key}/assets/{name}` (campo `asset.current.scan.status`) periodicamente (comece com 2 s, com backoff) até
  `scan.status` sair de `pending`. Não reenvie o arquivo.
- **422**: arquivo recusado pela varredura (`malware_detected`, `svg_unsafe`, `archive_encrypted`,
  `archive_bomb`, `archive_unsupported`). Não tente de novo com o mesmo conteúdo.

Exemplo: `curl -H "Authorization: Bearer $NBK" -H "Idempotency-Key: $(uuidgen)" -F file=@logo.png
-F name=logos/acme.png https://api.nebularws.com/v1/galleries/marcas-k7p2/assets`

Escopo exigido: `assets:write` · operationId: `uploadAsset`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `key` | path | string | sim | Chave pública imutável da galeria (ex.: `marcas-k7p2`). |
| `Idempotency-Key` | header | string | não | Chave de idempotência (até 255 caracteres; use um UUID). Mesma chave + mesmo corpo ⇒ mesma resposta. Mesma chave + corpo diferente ⇒ `409 idempotency_conflict`. |

### Corpo (multipart/form-data)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `file` | string | sim | Conteúdo do arquivo (até 25 MB). |
| `name` | string | não | Nome dentro da galeria: até 4 segmentos separados por `/`, `[a-z0-9._-]`, até 200 caracteres, sem `..`, sem segmento iniciando com `.` e com o primeiro segmento diferente de 12 caracteres hexadecimais. Inválido ⇒ `400 invalid_request`. Se omitido, usa o nome do arquivo enviado normalizado. |

### Resposta 201

Arquivo publicado (`scan.status = clean`).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `name` | string | sim |  |
| `gallery_key` | string | sim |  |
| `current` | object | sim |  |
| `current.id` | string | sim |  |
| `current.hash` | string | sim | SHA-256 hexadecimal do conteúdo. |
| `current.bytes` | integer | sim |  |
| `current.content_type` | string | sim | Detectado pelo conteúdo. |
| `current.class` | enum(image, svg, font, media, document, markup, archive, binary) | sim | Classe do arquivo, detectada pelo conteúdo. Define como a CDN serve o arquivo (ver descrição geral). |
| `current.width` | integer\|null | sim | Somente imagens. |
| `current.height` | integer\|null | sim | Somente imagens. |
| `current.variants` | array<string> | sim | Larguras de variantes geradas (imagens). |
| `current.scan` | object | sim |  |
| `current.scan.status` | enum(pending, clean, rejected, quarantined) | sim | `pending`: aguardando varredura, não publicado. `clean`: publicado. `rejected`: recusado. `quarantined`: detectado na varredura diária; deixou de ser servido (451). |
| `current.scan.reason` | string\|null | sim | Motivo da recusa ou quarentena. |
| `current.scan.engine` | string\|null | sim |  |
| `current.scan.scanned_at` | string\|null | sim |  |
| `current.url` | string\|null | sim | URL **imutável** (`https://<bucket>.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`), com `Cache-Control: public, max-age=31536000, immutable`; `null` enquanto o arquivo não estiver `clean`. Para imagens aceita `?w=640` (largura) e `?q=` (qualidade); o formato (AVIF/WebP) é negociado por `Accept` com `Vary: Accept`. Se a segregação de downloads estiver ligada, classes de download usam outro domínio; use sempre a URL devolvida pela API, sem montá-la. |
| `current.uploaded_by` | object | sim |  |
| `current.uploaded_by.kind` | enum(user, token) | sim |  |
| `current.uploaded_by.name` | string | sim |  |
| `current.created_at` | string | sim |  |
| `alias_url` | string\|null | sim | URL **alias** (`https://<bucket>.nebularcdn.com/<gallery_key>/<name>`), sempre a versão atual (`max-age=60, stale-while-revalidate=86400`); `null` enquanto não `clean`. Também aceita `?w=640`, ex.: `https://media.nebularcdn.com/marcas-k7p2/logos/acme.png?w=640`. |
| `versions_count` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "ast_01J9ZK8W",
  "name": "logos/acme.png",
  "gallery_key": "marcas-k7p2",
  "current": {
    "id": "ver_01J9ZK8X",
    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "bytes": 48213,
    "content_type": "image/png",
    "class": "image",
    "width": 1200,
    "height": 630,
    "variants": [
      "320",
      "640",
      "1280"
    ],
    "scan": {
      "status": "clean",
      "reason": null,
      "engine": "clamav",
      "scanned_at": "2026-10-09T14:05:02Z"
    },
    "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
    "uploaded_by": {
      "kind": "token",
      "name": "agente-deploy"
    },
    "created_at": "2026-10-09T14:05:01Z"
  },
  "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
  "versions_count": 1,
  "created_at": "2026-10-09T14:05:01Z"
}
```

### Resposta 202

Aceito, mas **ainda não publicado** (`scan.status = pending`). Consulte o `GET` do arquivo até
`scan.status` sair de `pending`. Enquanto `pending`, `content_type`/`class` são provisórios
(`application/octet-stream`/`binary`) e `width`/`height` são `null`; os valores reais só aparecem após `clean`.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `name` | string | sim |  |
| `gallery_key` | string | sim |  |
| `current` | object | sim |  |
| `current.id` | string | sim |  |
| `current.hash` | string | sim | SHA-256 hexadecimal do conteúdo. |
| `current.bytes` | integer | sim |  |
| `current.content_type` | string | sim | Detectado pelo conteúdo. |
| `current.class` | enum(image, svg, font, media, document, markup, archive, binary) | sim | Classe do arquivo, detectada pelo conteúdo. Define como a CDN serve o arquivo (ver descrição geral). |
| `current.width` | integer\|null | sim | Somente imagens. |
| `current.height` | integer\|null | sim | Somente imagens. |
| `current.variants` | array<string> | sim | Larguras de variantes geradas (imagens). |
| `current.scan` | object | sim |  |
| `current.scan.status` | enum(pending, clean, rejected, quarantined) | sim | `pending`: aguardando varredura, não publicado. `clean`: publicado. `rejected`: recusado. `quarantined`: detectado na varredura diária; deixou de ser servido (451). |
| `current.scan.reason` | string\|null | sim | Motivo da recusa ou quarentena. |
| `current.scan.engine` | string\|null | sim |  |
| `current.scan.scanned_at` | string\|null | sim |  |
| `current.url` | string\|null | sim | URL **imutável** (`https://<bucket>.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`), com `Cache-Control: public, max-age=31536000, immutable`; `null` enquanto o arquivo não estiver `clean`. Para imagens aceita `?w=640` (largura) e `?q=` (qualidade); o formato (AVIF/WebP) é negociado por `Accept` com `Vary: Accept`. Se a segregação de downloads estiver ligada, classes de download usam outro domínio; use sempre a URL devolvida pela API, sem montá-la. |
| `current.uploaded_by` | object | sim |  |
| `current.uploaded_by.kind` | enum(user, token) | sim |  |
| `current.uploaded_by.name` | string | sim |  |
| `current.created_at` | string | sim |  |
| `alias_url` | string\|null | sim | URL **alias** (`https://<bucket>.nebularcdn.com/<gallery_key>/<name>`), sempre a versão atual (`max-age=60, stale-while-revalidate=86400`); `null` enquanto não `clean`. Também aceita `?w=640`, ex.: `https://media.nebularcdn.com/marcas-k7p2/logos/acme.png?w=640`. |
| `versions_count` | integer | sim |  |
| `created_at` | string | sim |  |

```json
{
  "id": "ast_01J9ZK8W",
  "name": "logos/acme.png",
  "gallery_key": "marcas-k7p2",
  "current": {
    "id": "ver_01J9ZK8X",
    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "bytes": 48213,
    "content_type": "application/octet-stream",
    "class": "binary",
    "width": null,
    "height": null,
    "variants": [],
    "scan": {
      "status": "pending",
      "reason": null,
      "engine": null,
      "scanned_at": null
    },
    "url": null,
    "uploaded_by": {
      "kind": "token",
      "name": "agente-deploy"
    },
    "created_at": "2026-10-09T14:05:01Z"
  },
  "alias_url": null,
  "versions_count": 1,
  "created_at": "2026-10-09T14:05:01Z"
}
```

### Resposta 409

Mesma `Idempotency-Key` usada com um corpo diferente.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova."
}
```

### Resposta 413

Arquivo acima de 25 MB (ou 40 MP para imagens), ou cota do time excedida
(`payload_too_large` / `quota_exceeded`). Reduza o arquivo ou exclua arquivos antigos.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "payload_too_large",
  "message": "O arquivo excede o limite de 25 MB."
}
```

### Resposta 415

Tipo não reconhecido (`unsupported_type`), classe de arquivo não permitida no bucket
(`class_not_allowed`) ou extensão divergente do conteúdo detectado (`extension_mismatch`).
Corrija o nome ou o arquivo.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "unsupported_type",
  "message": "Este tipo de arquivo não é permitido neste bucket."
}
```

### Resposta 422

Recusado pela varredura: `malware_detected` (a mensagem traz o nome da detecção),
`svg_unsafe`, `archive_encrypted`, `archive_bomb` ou `archive_unsupported`. A amostra não é guardada. Não reenvie o mesmo conteúdo.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "malware_detected",
  "message": "Arquivo recusado: Win.Test.EICAR_HDB-1 detectado."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/galleries/{key}/assets/{name}`

Detalhe do arquivo, versões, URLs e varredura

Retorna a versão atual, o histórico de versões e o status de varredura. Use para consultar um upload
`pending` até que `scan.status` mude. Escopo exigido: `assets:read`.

Escopo exigido: `assets:read` · operationId: `getAsset`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `key` | path | string | sim | Chave pública imutável da galeria (ex.: `marcas-k7p2`). |
| `name` | path | string | sim | Nome do arquivo na galeria (até 4 segmentos separados por `/`, URL-encoded ou não, ex.: `logos%2Facme.png`). |

### Resposta 200

Arquivo.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `asset` | object | sim |  |
| `asset.id` | string | sim |  |
| `asset.name` | string | sim |  |
| `asset.gallery_key` | string | sim |  |
| `asset.current` | object | sim |  |
| `asset.current.id` | string | sim |  |
| `asset.current.hash` | string | sim | SHA-256 hexadecimal do conteúdo. |
| `asset.current.bytes` | integer | sim |  |
| `asset.current.content_type` | string | sim | Detectado pelo conteúdo. |
| `asset.current.class` | enum(image, svg, font, media, document, markup, archive, binary) | sim | Classe do arquivo, detectada pelo conteúdo. Define como a CDN serve o arquivo (ver descrição geral). |
| `asset.current.width` | integer\|null | sim | Somente imagens. |
| `asset.current.height` | integer\|null | sim | Somente imagens. |
| `asset.current.variants` | array<string> | sim | Larguras de variantes geradas (imagens). |
| `asset.current.scan` | object | sim |  |
| `asset.current.scan.status` | enum(pending, clean, rejected, quarantined) | sim | `pending`: aguardando varredura, não publicado. `clean`: publicado. `rejected`: recusado. `quarantined`: detectado na varredura diária; deixou de ser servido (451). |
| `asset.current.scan.reason` | string\|null | sim | Motivo da recusa ou quarentena. |
| `asset.current.scan.engine` | string\|null | sim |  |
| `asset.current.scan.scanned_at` | string\|null | sim |  |
| `asset.current.url` | string\|null | sim | URL **imutável** (`https://<bucket>.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`), com `Cache-Control: public, max-age=31536000, immutable`; `null` enquanto o arquivo não estiver `clean`. Para imagens aceita `?w=640` (largura) e `?q=` (qualidade); o formato (AVIF/WebP) é negociado por `Accept` com `Vary: Accept`. Se a segregação de downloads estiver ligada, classes de download usam outro domínio; use sempre a URL devolvida pela API, sem montá-la. |
| `asset.current.uploaded_by` | object | sim |  |
| `asset.current.uploaded_by.kind` | enum(user, token) | sim |  |
| `asset.current.uploaded_by.name` | string | sim |  |
| `asset.current.created_at` | string | sim |  |
| `asset.alias_url` | string\|null | sim | URL **alias** (`https://<bucket>.nebularcdn.com/<gallery_key>/<name>`), sempre a versão atual (`max-age=60, stale-while-revalidate=86400`); `null` enquanto não `clean`. Também aceita `?w=640`, ex.: `https://media.nebularcdn.com/marcas-k7p2/logos/acme.png?w=640`. |
| `asset.versions_count` | integer | sim |  |
| `asset.created_at` | string | sim |  |
| `versions` | array<object> | sim |  |
| `versions[].id` | string | sim |  |
| `versions[].hash` | string | sim | SHA-256 hexadecimal do conteúdo. |
| `versions[].bytes` | integer | sim |  |
| `versions[].content_type` | string | sim | Detectado pelo conteúdo. |
| `versions[].class` | enum(image, svg, font, media, document, markup, archive, binary) | sim | Classe do arquivo, detectada pelo conteúdo. Define como a CDN serve o arquivo (ver descrição geral). |
| `versions[].width` | integer\|null | sim | Somente imagens. |
| `versions[].height` | integer\|null | sim | Somente imagens. |
| `versions[].variants` | array<string> | sim | Larguras de variantes geradas (imagens). |
| `versions[].scan` | object | sim |  |
| `versions[].scan.status` | enum(pending, clean, rejected, quarantined) | sim | `pending`: aguardando varredura, não publicado. `clean`: publicado. `rejected`: recusado. `quarantined`: detectado na varredura diária; deixou de ser servido (451). |
| `versions[].scan.reason` | string\|null | sim | Motivo da recusa ou quarentena. |
| `versions[].scan.engine` | string\|null | sim |  |
| `versions[].scan.scanned_at` | string\|null | sim |  |
| `versions[].url` | string\|null | sim | URL **imutável** (`https://<bucket>.nebularcdn.com/<gallery_key>/<hash[0:12]>/<name>`), com `Cache-Control: public, max-age=31536000, immutable`; `null` enquanto o arquivo não estiver `clean`. Para imagens aceita `?w=640` (largura) e `?q=` (qualidade); o formato (AVIF/WebP) é negociado por `Accept` com `Vary: Accept`. Se a segregação de downloads estiver ligada, classes de download usam outro domínio; use sempre a URL devolvida pela API, sem montá-la. |
| `versions[].uploaded_by` | object | sim |  |
| `versions[].uploaded_by.kind` | enum(user, token) | sim |  |
| `versions[].uploaded_by.name` | string | sim |  |
| `versions[].created_at` | string | sim |  |

```json
{
  "asset": {
    "id": "ast_01J9ZK8W",
    "name": "logos/acme.png",
    "gallery_key": "marcas-k7p2",
    "current": {
      "id": "ver_01J9ZK8X",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "bytes": 48213,
      "content_type": "image/png",
      "class": "image",
      "width": 1200,
      "height": 630,
      "variants": [
        "320",
        "640",
        "1280"
      ],
      "scan": {
        "status": "clean",
        "reason": null,
        "engine": "clamav",
        "scanned_at": "2026-10-09T14:05:02Z"
      },
      "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
      "uploaded_by": {
        "kind": "token",
        "name": "agente-deploy"
      },
      "created_at": "2026-10-09T14:05:01Z"
    },
    "alias_url": "https://media.nebularcdn.com/marcas-k7p2/logos/acme.png",
    "versions_count": 1,
    "created_at": "2026-10-09T14:05:01Z"
  },
  "versions": [
    {
      "id": "ver_01J9ZK8X",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "bytes": 48213,
      "content_type": "image/png",
      "class": "image",
      "width": 1200,
      "height": 630,
      "variants": [
        "320",
        "640",
        "1280"
      ],
      "scan": {
        "status": "clean",
        "reason": null,
        "engine": "clamav",
        "scanned_at": "2026-10-09T14:05:02Z"
      },
      "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
      "uploaded_by": {
        "kind": "token",
        "name": "agente-deploy"
      },
      "created_at": "2026-10-09T14:05:01Z"
    }
  ]
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## DELETE `/v1/galleries/{key}/assets/{name}`

Exclui o arquivo

Exclui o arquivo e purga o cache da CDN. O backup retém os bytes por 30 dias. Escopo exigido:
`assets:write`.

Escopo exigido: `assets:write` · operationId: `deleteAsset`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `key` | path | string | sim | Chave pública imutável da galeria (ex.: `marcas-k7p2`). |
| `name` | path | string | sim | Nome do arquivo na galeria (até 4 segmentos separados por `/`, URL-encoded ou não, ex.: `logos%2Facme.png`). |

### Resposta 204

Excluído.

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/abuso.md

# Abuso (referência)

## POST `/v1/abuse`

Denuncia uma URL hospedada na CDN

Endpoint **público**: não exige token. Sujeito a rate-limit por IP. Escopo: nenhum.
O operador analisa e tira do ar o que violar as regras.

Escopo exigido: - · operationId: `reportAbuse`

### Corpo (application/json)

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `url` | string | sim |  |
| `reason` | string | sim |  |
| `contact` | string | não | E-mail para retorno (opcional). |

```json
{
  "url": "https://media.nebularcdn.com/marcas-k7p2/9f86d081884c/logos/acme.png",
  "reason": "Arquivo malicioso hospedado.",
  "contact": "denunciante@exemplo.org"
}
```

### Resposta 202

Denúncia recebida.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `status` | string | não |  |

```json
{
  "status": "received"
}
```

### Resposta 422

Corpo inválido (URL ausente ou fora da CDN, motivo vazio).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, not_found, payload_too_large, quota_exceeded, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

```json
{
  "error": "invalid_request",
  "message": "Informe uma URL da CDN e o motivo da denúncia."
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `429` Limite de requisições excedido. Espere `Retry-After` segundos; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

---

URL: https://docs.nebularws.com/referencia/changelog.md

# Changelog da API

## 1.0.0

- API pública `/v1` de galerias e arquivos para agents (tokens `nbk_`), com varredura antes da publicação, idempotência em uploads e paginação por cursor.
- `POST /v1/abuse` público para denúncias.

## v13 (em construção)

Projetos, serviços, deploys, variáveis, volumes, bancos, domínios e templates. Esta página será atualizada quando as rotas forem publicadas.

---

URL: https://docs.nebularws.com/agents/index.md

# Para agents

## Como ler

- [`/llms.txt`](/llms.txt): índice no formato llmstxt.org, com título e descrição de cada página.
- [`/llms-full.txt`](/llms-full.txt): toda a documentação em texto puro, na ordem de tutorial.
- Qualquer página em Markdown cru: acrescente `.md` à URL (por exemplo `/comecar/token.md`). Cada página HTML aponta para sua versão com `<link rel="alternate" type="text/markdown">`.
- Sem cookies e sem JavaScript obrigatório: um `GET` simples lê tudo.

## Guias para tarefas grandes

- [Contrato de App Nebular](/agents/contrato-app/): o documento para mandar a um agent que vai adequar um app à Nebular; regras normativas (porta, disco somente leitura, config, banco) e tabela de erros de deploy com culpa e correção.
- [Deploy de aplicações com vários serviços](/agents/deploy-multi-servico/): front, API, worker e bancos no mesmo projeto, com referências, deploy em grupo, rollback, erros e o que ainda não existe (manifesto, réplicas).
- [Como corrigir cada erro de deploy](/agents/corrigir-deploy/): cookbook com uma seção por `error_code` (âncora estável), o que cada erro significa, como corrigir e de quem é a culpa; inclui migrar SQLite local para libSQL gerenciado.
- [Preparar o app para rodar e escalar](/operacao/app-pronto-para-escalar/): use antes do primeiro deploy; cobre `0.0.0.0:$PORT`, app sem estado, health check, SIGTERM, volumes e migrations.
- [Variáveis e referências](/conectados/variaveis-e-referencias/): use ao configurar ambiente; explica as variáveis automáticas e as referências `${{serviço.VAR}}`.
- [Conexão e referências de banco](/bancos/conexao-e-referencias/): use ao ligar app e banco; o banco **não** é injetado sozinho, a ligação é um passo explícito resolvido no deploy.
- [Sugestões de persistência](/conectados/sugestoes-de-persistencia/): quando um app precisa de volume ou banco, a plataforma detecta e sugere criar; leia e descarte sugestões pela API, sempre com autorização.

## Faça

- Autentique com `Authorization: Bearer $NEBULAR_TOKEN`, lendo o token do ambiente.
- Use `Idempotency-Key` em todo envio automatizado.
- Decida pelo campo `error` e siga a [tabela de erros](/erros/tabela/).
- Trate páginas “em construção — disponível na v13” como **recursos inexistentes**: não invente rotas.

## Não faça

- Não coloque o token em query string, log, prompt ou repositório.
- Não repita um `4xx` (exceto `429`) sem alterar a requisição.
- Não reenvie um arquivo recusado por varredura.
- Não monte URLs da CDN à mão: use `url` e `alias_url` devolvidas pela API.

---

URL: https://docs.nebularws.com/agents/contrato-app.md

# Contrato de App Nebular (para agents)

**Este é o documento para colar ou mandar a um agent de IA que vai preparar um app para a Nebular.** Ele é curto e normativo: cada "DEVE" é uma regra que a plataforma faz valer. O detalhe e os porquês estão em [App pronto para a Nebular e para escalar](/operacao/app-pronto-para-escalar/); aqui só o contrato.

## Regras (o app DEVE)

1. **Escutar em `0.0.0.0:$PORT`.** Ler `PORT` do ambiente; se ausente, usar `8080`. Nunca `127.0.0.1`, `localhost` nem porta fixa diferente da `port` declarada no serviço. Portas abaixo de 1024 não existem.
2. **Tratar o disco como somente leitura.** A raiz e `/app` não aceitam escrita. Escrever **só** em volume montado ou em `/tmp`/`$TMPDIR` (64 MB, memória, apagado a cada deploy). O caminho de dados vem de variável de ambiente (ex.: `DB_FILE`, `DATA_DIR`) apontando para o [volume](/conectados/volumes/), nunca fixo no código. Assets e arquivos gerados são criados **no build**, não no boot.
3. **Configurar tudo por variável de ambiente**, com default seguro. Se faltar algo crítico (chave, URL, caminho), **falhar no boot com mensagem clara** e sair com código diferente de 0. Não cair em silêncio num default de desenvolvimento. Segredo nunca no repositório nem em `NEXT_PUBLIC_*`/`VITE_*`.
4. **Ligar o banco por referência.** O banco **não** é injetado automaticamente: o serviço do app define uma variável como `DATABASE_URL = ${{db.DATABASE_URL}}` (`db` é o nome do serviço-banco), resolvida no deploy. Nunca montar hostname ou URL à mão. Veja [Conexão e referências](/bancos/conexao-e-referencias/).
5. **Usar as variáveis automáticas** que a plataforma injeta em todo serviço, sem você definir: `PORT`, `PRIVATE_URL`, `PRIVATE_HOST`, `PUBLIC_URL`, `PUBLIC_DOMAIN`, `NEBULAR_SERVICE_NAME`. Para falar com outro serviço use a referência `${{api.PRIVATE_URL}}`. Lista e regras em [Variáveis e referências](/conectados/variaveis-e-referencias/). Não invente outras.
6. **Higiene de processo** (detalhe em [App pronto para escalar](/operacao/app-pronto-para-escalar/)):
   - **Escute primeiro, faça o trabalho pesado depois**: bindar `0.0.0.0:$PORT` e responder o health check (`GET` rápido, 2xx/3xx, sem migration nem chamada a terceiros) **antes** de qualquer tarefa longa. Importação, seed e migração de dados rodam **em segundo plano** (async), depois que a porta já está no ar — nunca no caminho do boot que trava a abertura da porta. Esse é o jeito robusto: a janela de ativação não estoura e a nova versão entra sem falhar.
   - **`SIGTERM` gracioso**: parar de aceitar conexões, terminar as em andamento e sair com 0.
   - **Logs em stdout, uma linha JSON por evento**; em falha de boot, logar a causa antes de sair.
   - **Migrations idempotentes**, com lock e compatíveis com a versão anterior.
   - **Sem estado local** (12-factor): sessão, fila, lock e upload não ficam na memória nem no disco do container; sem cron interno.
7. **Go com vários programas em `cmd/`.** A plataforma escolhe por convenção (`server`, `app`, `api`, `web`, `gateway`, `http`, `service`, `main`, `cmd`, nessa prioridade). Se não decidir ou se não for o que você quer, defina `build_command` no serviço. O binário DEVE sair em `/app/app`. Detalhe em [Go](/guia/go/#vários-programas-em-cmd).

### Boot lento: aumentar a janela de health check (`healthcheck_start_period`)

A ativação de uma nova versão espera o app responder 2xx/3xx no health check por uma janela de **60s** antes de trocar o tráfego. O padrão da casa é a regra 6 acima — **escute primeiro, importe/semeie depois, em segundo plano**. Quando o app **precisa mesmo** fazer trabalho longo no boot antes de escutar (e não dá para rodar async), aumente essa janela no serviço com o campo `healthcheck_start_period` (em segundos) em `POST`/`PATCH .../services`: `0` (padrão) mantém os 60s; um valor maior dá mais tempo ao primeiro 2xx/3xx, até o teto de **900s**. **Trade-off**: uma janela maior atrasa a detecção de uma versão que subiu quebrada, então use só quando o boot longo for inevitável — escutar primeiro continua sendo o jeito certo.

## Classificação de erros de deploy

Um deploy que falha termina em `failed` com um `error.code` estável ([Deploys e status](/operacao/deploys-e-status/)); a versão anterior continua no ar. Leia o log de build e do container ([Logs](/operacao/logs/)) antes de mexer no código. Para o remédio passo a passo de cada código, com âncora por `error_code`, veja o cookbook [Como corrigir cada erro de deploy](/agents/corrigir-deploy/) — o `fix_url` de cada erro aponta para a seção correspondente lá.

| Sintoma ou `error_code` | Culpa | Correção |
|---|---|---|
| `activate_no_http` | App | Escutar em `0.0.0.0:$PORT`, declarar `port` igual, abrir a porta antes do trabalho pesado e corrigir o `healthcheck_path` se devolve 4xx/5xx. App que **precisa** importar/semear no boot: suba a janela do serviço com `healthcheck_start_period` (veja abaixo). |
| `activate_readonly_write` | App | Escrever só em volume ou `/tmp`; ou gerar o arquivo no build. Banco SQLite em disco somente-leitura? [Migrar para libSQL gerenciado](/agents/corrigir-deploy/#migrar-sqlite-local-para-gerenciado). |
| `activate_app_crashed` | App | Ver o log do container. Quase sempre é variável faltando, arquivo ausente ou escrita em disco somente leitura. Se o log mostra gravação de arquivo de banco em disco somente-leitura, [migre o SQLite para libSQL gerenciado](/agents/corrigir-deploy/#migrar-sqlite-local-para-gerenciado). |
| `activate_oom` | App | Reduzir memória (caches, concorrência) ou subir `resources.memory_mb` / de plano. |
| `build_clone_failed` | App ou configuração | Conferir repositório, branch e a instalação GitHub do serviço. |
| `build_failed`, `build_install_failed`, `build_script_failed`, `build_detect_failed`, `build_copy_failed` | App ou configuração | Ler o log de build; fixar versões; declarar `build.builder`/`build_command`; `root_dir` correto em monorepo. |
| `build_oom`, `build_timeout`, `build_disk_full` | App | Reduzir paralelismo e o que entra no artefato; tirar etapas pesadas do build. |
| `image_requires_root` | App | Declarar `build.user` (`uid[:gid]`, nunca root) ou usar imagem sem privilégio. |
| `unresolved_reference` (`422` ao disparar o deploy) | App ou configuração | Criar a variável ou serviço citado, ou corrigir o nome na referência. |
| Detecção de stack: vários mains em `cmd/` | Plataforma escolhe por convenção; se não decidir, é configuração | Definir `build_command`, por exemplo `go build -o /app/app ./cmd/server`. |

Falha com outro código, ou que persiste com o app correto: não é culpa do app. Reporte o `error.code`, o `id` do deploy e a hora ([Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/), [Tabela de erros](/erros/tabela/)).

Quando a falha é por **falta de persistência** — `activate_readonly_write` (o app grava num caminho somente-leitura), conexão recusada a um banco inexistente ou `unresolved_reference` apontando a um banco que não existe — a plataforma também registra uma **sugestão**: ela detecta o que faltou (volume ou banco gerenciado) e oferece criar, esperando sua autorização. Veja [Sugestões de persistência](/conectados/sugestoes-de-persistencia/) para ler e tratar essas sugestões pela API.

---

URL: https://docs.nebularws.com/agents/deploy-multi-servico.md

# Deploy de aplicações com vários serviços (guia para agentes)

Este guia é para um **agent** que recebeu a tarefa de publicar uma aplicação com várias partes (front, API, worker, bancos) na Nebular. Ele usa só a API pública `/v1`. Tudo aqui foi conferido contra a API; o que a plataforma **não** faz está na seção [O que não é suportado](#o-que-não-é-suportado).

## Resumo para LLM

```text
NEBULAR MULTI-SERVIÇO (resumo). Base: https://api.nebularws.com/v1. Auth: Authorization: Bearer $NEBULAR_TOKEN (nunca em URL/log).
MODELO: projeto = grupo de serviços numa rede privada. kind só "app" (seu código/imagem) ou "database" (postgres|mariadb|sqlite). NÃO existe kind worker/cron.
NÃO EXISTE: manifesto declarativo (nebular.json/compose), réplicas/escala horizontal (1 container por serviço), template próprio do time, rollback de grupo, webhooks.
FLUXO: POST /projects -> POST /projects/{p}/databases (espere status=ready) -> POST /projects/{p}/services (visibility private por padrão; o "web" já nasce público, use PATCH) -> PUT .../variables (bulk) e .../shared-variables com ${{svc.VAR}} -> código: POST .../services/{s}/deployments (multipart "file") em ordem api -> worker/web, OU imagem/git + POST /projects/{p}/deploy {} -> GET /projects/{p}/group-deployments/{g} até ready -> verificar public_url -> rollback por serviço: POST .../deployments/{d}/rollback.
REFERÊNCIAS: ${{db.DATABASE_URL}}, ${{api.PRIVATE_URL}} (=http://api:PORT), ${{jobs.LIBSQL_URL}}, ${{shared.X}}. Variável shared só chega ao serviço se ele a referenciar. Resolvidas no deploy. Literal "${{" escreva "$${{".
ESCOPOS: projects:read projects:write deploy env:write databases:write volumes:write domains:write logs:read (env:reveal só humano, não peça).
REGRAS DE RUNTIME: o app escuta 0.0.0.0:$PORT e responde 2xx/3xx em healthcheck_path (worker também precisa de HTTP); disco é somente leitura: grave em /tmp (64 MB) ou num volume em /app/<pasta> (1 por serviço, 1 a 50 GB); sem SMTP direto.
ERROS: 4xx (menos 429) = corrija; 429/503 = espere Retry-After; 401/403/quota_exceeded/project_quota_exceeded = pare e avise a pessoa; 409 deploy_in_progress = acompanhe o deploy em curso; 422 unresolved_reference|reference_cycle = corrija variáveis (nada foi criado).
DEPLOY ASSÍNCRONO: faça polling 2 s dobrando até 30 s. Deploy falho não dá erro HTTP: veja status=failed e error.code/message (activate_readonly_write, activate_no_http, build_storage_unavailable...).
IDEMPOTÊNCIA: Idempotency-Key (8-128 [A-Za-z0-9._:-]) em todo POST que cria/dispara; mesma chave+mesmo corpo em 24 h repete a resposta; corpo diferente = 422 idempotency_conflict.
LIMITES: GET /v1/limits (hobby: 10 serviços, 3 bancos, 20 GB de volume, 4096 MB, 30 deploys/h por time). Cada deploy de cada serviço conta.
DESTRUTIVO: apagar volume/banco/serviço/projeto só com ordem explícita da pessoa. Nunca imprima valor de variável sensível.
```

## O que existe

| Pergunta | Resposta (verificada) |
|---|---|
| Há um arquivo para declarar a aplicação inteira (`nebular.json`, `nebular.toml`, compose)? | **Não.** O fluxo é imperativo: você cria projeto, bancos, serviços e variáveis por chamadas e depois dispara o deploy. Veja [Manifesto declarativo](#manifesto-declarativo-não-existe-ainda). |
| Há várias partes no mesmo projeto? | **Sim.** Um projeto é um grupo de serviços na mesma rede privada, com variáveis `shared` (usadas por referência `${{shared.NOME}}`) e deploy em grupo ordenado pelas referências. |
| Tipos de serviço | Só `app` e `database`. Um worker é um `app` privado; **não existe** `kind` worker nem cron. |
| Réplicas, escala horizontal, balanceamento entre instâncias | **Não existem.** Cada serviço é um único container; o nome privado aponta para ele. O que há: mais memória e CPU por serviço (`resources`). |
| Template com vários serviços | Existe só o **catálogo da plataforma** (hoje `wordpress`: MariaDB + app). O time **não** cadastra templates próprios. |
| Bancos gerenciados | `postgres`, `mariadb` e `sqlite` (libSQL), entregues ao app por variável e referência. |

## Pré-requisitos

1. **Token de API** do time (`nbk_…`), criado por uma **pessoa** com papel admin e confirmação recente de identidade, no painel: Time, Configurações, Tokens de API ([Token de API](/comecar/token/)). Escopos para este guia:

   | Passo | Escopo |
   |---|---|
   | ler token, limites, projetos, serviços, deploys, bancos | `projects:read` |
   | criar projeto e serviços, mudar recursos | `projects:write` |
   | criar bancos | `databases:write` |
   | variáveis e referências | `env:write` (e `env:read` para listar) |
   | volume | `volumes:write` |
   | deploy, grupo, rollback, enviar código | `deploy` |
   | domínio próprio | `domains:write` |
   | logs de build e de runtime | `logs:read` |

   O token **não** pode ser restrito a projetos específicos se você vai criar o projeto: token restrito responde `403` em `POST /v1/projects`. Não peça `env:reveal`: ele devolve segredos em claro e só nasce com confirmação de identidade da pessoa. O app recebe as credenciais por variável; o agent nunca precisa vê-las.
2. Ferramentas: `curl`, `jq`, `tar`. O código de cada serviço no disco (ou imagens públicas com digest, ou repositório GitHub já conectado ao time por uma pessoa).
3. Variáveis de ambiente: `NEBULAR_API=https://api.nebularws.com` e `NEBULAR_TOKEN` (segredo do ambiente; nunca no prompt, em log ou em arquivo versionado).

```bash
H="Authorization: Bearer $NEBULAR_TOKEN"
curl -sS "$NEBULAR_API/v1/me" -H "$H" | jq -e '.token.scopes | index("deploy") != null' >/dev/null
curl -sS "$NEBULAR_API/v1/limits" -H "$H"
```
```json
{"plan": "hobby", "services": {"used": 1, "max": 10}, "memory_mb": {"used": 512, "max": 4096}, "volumes_gb": {"used": 0, "max": 20}, "databases": {"used": 0, "max": 3}, "deploys_per_hour": {"used": 0, "max": 30}}
```

Antes de começar, confirme que cabe: serviços de aplicação, bancos, memória e volume do plano (`GET /v1/limits`). Um deploy completo desta receita usa 3 deploys da cota `deploys_per_hour`.

## Como as peças se encaixam

```mermaid
flowchart LR
  U[Internet] --> W[web: Next.js, public]
  W -- API_URL=${{api.PRIVATE_URL}} --> A[api: Go, private, volume /app/uploads]
  K[worker: Node, private] -- API_URL=${{api.PRIVATE_URL}} --> A
  A -- DATABASE_URL=${{db.DATABASE_URL}} --> D[(db: Postgres)]
  K -- DATABASE_URL=${{db.DATABASE_URL}} --> D
  K -- LIBSQL_URL=${{jobs.LIBSQL_URL}} --> J[(jobs: SQLite libSQL)]
```

Regras do modelo que decidem o desenho:

- **Rede privada.** Serviços do mesmo projeto se resolvem pelo `name`: `api` é alcançável em `http://api:<port>`. Use `${{api.PRIVATE_URL}}`, não monte a URL. Outro projeto nunca é alcançável ([Rede privada](/conectados/rede-privada/)).
- **Bancos não ficam na rede privada.** Moram num nó de banco e são acessados pela URL das variáveis, sempre com TLS. Só os serviços do projeto conseguem abrir a conexão.
- **Visibilidade.** `visibility` omitida = `private`. Só o que precisa de URL pública vira `public` (e então exige `slug`). Todo projeto novo já nasce com um serviço `web` **público**; adapte-o com `PATCH` em vez de criar outro.
- **Ordem do deploy em grupo.** Vem das referências: quem é referenciado sobe antes. Neste exemplo `api` sobe primeiro; `worker` e `web` (que referenciam a `api`) sobem depois, em paralelo (até 4 por camada).
- **Variável compartilhada (`shared`) só chega ao serviço se ele a referenciar** (`${{shared.APP_ENV}}`). Defini-la não a injeta em ninguém.
- **Resolução no deploy.** Referência para algo que não existe só falha ao disparar o deploy, com `422`.

## O exemplo: app "pedidos"

| Serviço | Tipo | Stack | Visibilidade | Porta | O que faz |
|---|---|---|---|---|---|
| `db` | database | Postgres | n/a | n/a | dados dos pedidos |
| `jobs` | database | SQLite (libSQL) | n/a | n/a | estado do worker |
| `api` | app | Go (`builder: go`) | `private` | 8080 | regra de negócio; grava anexos no volume `/app/uploads` |
| `worker` | app | Node (`builder: node`) | `private` | 8081 | consome trabalho em segundo plano; expõe `/healthz` porque a plataforma exige HTTP |
| `web` | app | Node ou Next.js (`builder: node`) | `public` | 3000 | front; chama a `api` **no servidor** |

Para o teste ser real mesmo sem o seu código, os três serviços abaixo usam só a biblioteca padrão e respondem em `/status` dizendo, **sem imprimir segredo**, se as variáveis chegaram, se o banco é alcançável, se o volume é gravável e se um serviço enxerga o outro. Troque pelo seu código depois (Next.js com `"start": "next start"`, driver de Postgres etc.): o contrato de deploy é o mesmo.

Arquivos de `api/` (Go):

```go
// api/main.go
package main

import (
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"
)

func set(k string) bool { return os.Getenv(k) != "" }

// reach tenta abrir TCP até host:port.
func reach(host, port string) bool {
	if host == "" || port == "" {
		return false
	}
	c, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), 3*time.Second)
	if err != nil {
		return false
	}
	c.Close()
	return true
}

// writable diz se o app consegue gravar em dir.
func writable(dir string) bool {
	f := dir + "/.probe"
	if err := os.WriteFile(f, []byte("ok"), 0o600); err != nil {
		return false
	}
	return os.Remove(f) == nil
}

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) { w.Write([]byte("ok")) })
	mux.HandleFunc("GET /status", func(w http.ResponseWriter, _ *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprintf(w, `{"service":"api","app_env":%q,"database_url_set":%t,"db_reachable":%t,"uploads_writable":%t,"tmp_writable":%t}`,
			os.Getenv("APP_ENV"), set("DATABASE_URL"), reach(os.Getenv("PGHOST"), os.Getenv("PGPORT")),
			writable("/app/uploads"), writable("/tmp"))
	})
	log.Fatal(http.ListenAndServe("0.0.0.0:"+port, mux))
}
```

```text
# api/go.mod
module api

go 1.22
```

Arquivos de `worker/` (Node):

```json
{ "name": "worker", "version": "1.0.0", "scripts": { "start": "node worker.js" } }
```

```js
// worker/worker.js
const http = require("node:http");
const net = require("node:net");
const set = (k) => Boolean(process.env[k]);

const tcp = (host, port) =>
  new Promise((resolve) => {
    if (!host || !port) return resolve(false);
    const s = net.connect({ host, port: Number(port), timeout: 3000 });
    s.on("connect", () => { s.destroy(); resolve(true); });
    s.on("error", () => resolve(false));
    s.on("timeout", () => { s.destroy(); resolve(false); });
  });

// http1: qualquer status HTTP conta como "alcançável".
async function http1(url, path) {
  try {
    const r = await fetch(url + path, { signal: AbortSignal.timeout(3000) });
    return { ok: true, status: r.status, body: await r.json().catch(() => null) };
  } catch { return { ok: false }; }
}

async function status() {
  const api = process.env.API_URL ? await http1(process.env.API_URL, "/status") : { ok: false };
  const jobs = process.env.LIBSQL_URL ? await http1(process.env.LIBSQL_URL, "/") : { ok: false };
  return {
    service: "worker", app_env: process.env.APP_ENV || "",
    database_url_set: set("DATABASE_URL"), db_reachable: await tcp(process.env.PGHOST, process.env.PGPORT),
    libsql_set: set("LIBSQL_URL") && set("LIBSQL_AUTH_TOKEN"), libsql_reachable: jobs.ok,
    api_reachable: api.ok, api_status: api.body,
  };
}

http.createServer(async (req, res) => {
  if (req.url === "/healthz") return res.end("ok");
  if (req.url === "/status") { res.setHeader("Content-Type", "application/json"); return res.end(JSON.stringify(await status())); }
  res.statusCode = 404; res.end();
}).listen(Number(process.env.PORT || 8081), "0.0.0.0");

// laço do worker: troque pelo seu consumidor de fila.
setInterval(async () => console.log("tick", JSON.stringify({ api_reachable: (await status()).api_reachable })), 60000);
```

Arquivos de `web/` (Node; num Next.js real o `start` é `next start`):

```json
{ "name": "web", "version": "1.0.0", "scripts": { "start": "node server.js" } }
```

```js
// web/server.js
const http = require("node:http");

http.createServer(async (req, res) => {
  if (req.url === "/healthz") return res.end("ok");
  if (req.url === "/status") {
    let api = null;
    try {
      const r = await fetch(process.env.API_URL + "/status", { signal: AbortSignal.timeout(3000) });
      api = await r.json();
    } catch { /* api inalcançável: devolve null */ }
    res.setHeader("Content-Type", "application/json");
    return res.end(JSON.stringify({ service: "web", app_env: process.env.APP_ENV || "", api }));
  }
  res.end("pedidos: ok");
}).listen(Number(process.env.PORT || 3000), "0.0.0.0");
```

## Passo a passo

Os blocos abaixo formam **uma sessão de shell** (as variáveis `P`, `DB`, `API` etc. continuam entre eles). Se a sessão cair, recapture os ids com `GET /v1/projects` e `GET /v1/projects/{p}/services`. Os ids são opacos (ULID de 26 caracteres).

### 1. Preparar a sessão e o projeto

`R` é o sufixo único da execução: nome do projeto, `slug` público e prefixo das `Idempotency-Key`. Reexecutar com o **mesmo** `R` repete as respostas em vez de duplicar (24 h).

```bash
H="Authorization: Bearer $NEBULAR_TOKEN"; J="Content-Type: application/json"; B="$NEBULAR_API/v1"
R="pedidos-$(date +%s)"

# espera URL: polling com backoff até ready; falha em estado terminal ruim ou depois de ~10 min
espera() {
  local d=2 st
  for i in $(seq 1 40); do
    st=$(curl -sS "$1" -H "$H" | jq -r .status)
    case "$st" in
      ready) return 0 ;;
      failed|blocked|canceled|superseded|error) echo "terminou em $st: $1" >&2; return 1 ;;
    esac
    sleep "$d"; d=$(( d * 2 > 30 ? 30 : d * 2 ))
  done
  echo "tempo esgotado: $1" >&2; return 1
}

P=$(curl -sS -X POST "$B/projects" -H "$H" -H "$J" -H "Idempotency-Key: $R-projeto" \
  -d "{\"name\": \"$R\"}" | jq -r .id)
echo "projeto $P"
```

Erros: `403` (falta `projects:write`, ou o token é restrito a projetos), `409 project_quota_exceeded` (limite de projetos do time: pare e avise), `409 slug_taken` (outro nome).

### 2. Criar os bancos e esperar ficarem prontos

`quota_mb` é a cota de cada banco; acima dela o banco fica somente leitura. Os bancos nascem em `provisioning`: **só siga quando ambos estiverem `ready`**, porque as referências a um banco não pronto não resolvem.

```bash
DB=$(curl -sS -X POST "$B/projects/$P/databases" -H "$H" -H "$J" -H "Idempotency-Key: $R-db" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' | jq -r .id)
JOBS=$(curl -sS -X POST "$B/projects/$P/databases" -H "$H" -H "$J" -H "Idempotency-Key: $R-jobs" \
  -d '{"name": "jobs", "engine": "sqlite", "quota_mb": 256}' | jq -r .id)
espera "$B/projects/$P/databases/$DB" && espera "$B/projects/$P/databases/$JOBS"
```

Erros: `422 quota_exceeded` (limite de bancos do plano: pare e avise), `503 unavailable` (nó de banco indisponível: repita com backoff), `403` (falta `databases:write`).

### 3. Criar os serviços de aplicação

`source: {"type": "upload"}` significa que o código chega por upload (passo 7). `healthcheck_path` precisa responder 2xx ou 3xx. O `web` já existe: use `PATCH`.

```bash
API=$(curl -sS -X POST "$B/projects/$P/services" -H "$H" -H "$J" -H "Idempotency-Key: $R-api" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080,
       "source": {"type": "upload"}, "build": {"builder": "go"}, "healthcheck_path": "/healthz"}' | jq -r .id)

WORKER=$(curl -sS -X POST "$B/projects/$P/services" -H "$H" -H "$J" -H "Idempotency-Key: $R-worker" \
  -d '{"name": "worker", "kind": "app", "visibility": "private", "port": 8081,
       "source": {"type": "upload"}, "build": {"builder": "node"}, "healthcheck_path": "/healthz"}' | jq -r .id)

WEB=$(curl -sS -X PATCH "$B/projects/$P/services/web" -H "$H" -H "$J" \
  -d "{\"visibility\": \"public\", \"slug\": \"$R\", \"port\": 3000,
       \"source\": {\"type\": \"upload\"}, \"build\": {\"builder\": \"node\"}, \"healthcheck_path\": \"/healthz\"}" | jq -r .id)

# volume da api: 1 por serviço, em subpasta de /app (o resto de /app é somente leitura)
curl -sS -X PUT "$B/projects/$P/services/$API/volume" -H "$H" -H "$J" \
  -d '{"mount_path": "/app/uploads", "size_gb": 1}'
```

Campos opcionais do serviço: `start_command` e `build_command` (até 1024 caracteres, substituem o padrão), `resources` (`memory_mb`, `cpus`; padrão 512 MB e 0,5 CPU, máximo do plano), `auto_deploy` (deploy por git) e, nas fontes `git`, `root_dir` e `watch_paths`. `build.builder` aceita `auto`, `node`, `go`, `rust`, `python`, `static` e `dockerfile`.

Erros: `409 name_taken` (já existe serviço com esse nome; todo projeto traz um `web`), `409 slug_taken`, `422 quota_exceeded` (limite de serviços do plano: pare), `400 invalid_request` (campo desconhecido, p.ex. `memory_mb` solto: use `"resources": {"memory_mb": ...}`; ou campo fora das regras: `name` deve casar `^[a-z][a-z0-9-]{0,30}$`; `slug` em serviço `private` também é recusado), `400` no volume (`mount_path` proibido como `/app` inteiro, `/tmp`, `/etc`; ou `size_gb` fora de 1 a 50).

### 4. Variáveis e referências

Variáveis `shared` valem para o projeto, mas **cada serviço precisa referenciá-las**. O `PUT` em lote grava de 1 a 200 variáveis, tudo ou nada. Marque `sensitive: true` no que for segredo ou aponta para segredo; o valor deixa de voltar nas leituras.

```bash
curl -sS -X PUT "$B/projects/$P/shared-variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "APP_ENV",   "value": "production"},
  {"name": "LOG_LEVEL", "value": "info"}]}' >/dev/null

curl -sS -X PUT "$B/projects/$P/services/$API/variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "APP_ENV",      "value": "${{shared.APP_ENV}}"},
  {"name": "LOG_LEVEL",    "value": "${{shared.LOG_LEVEL}}"},
  {"name": "DATABASE_URL", "value": "${{db.DATABASE_URL}}", "sensitive": true},
  {"name": "PGHOST",       "value": "${{db.PGHOST}}"},
  {"name": "PGPORT",       "value": "${{db.PGPORT}}"}]}' >/dev/null

curl -sS -X PUT "$B/projects/$P/services/$WORKER/variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "APP_ENV",           "value": "${{shared.APP_ENV}}"},
  {"name": "DATABASE_URL",      "value": "${{db.DATABASE_URL}}", "sensitive": true},
  {"name": "PGHOST",            "value": "${{db.PGHOST}}"},
  {"name": "PGPORT",            "value": "${{db.PGPORT}}"},
  {"name": "LIBSQL_URL",        "value": "${{jobs.LIBSQL_URL}}"},
  {"name": "LIBSQL_AUTH_TOKEN", "value": "${{jobs.LIBSQL_AUTH_TOKEN}}", "sensitive": true},
  {"name": "API_URL",           "value": "${{api.PRIVATE_URL}}"}]}' >/dev/null

curl -sS -X PUT "$B/projects/$P/services/$WEB/variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "APP_ENV",  "value": "${{shared.APP_ENV}}"},
  {"name": "API_URL",  "value": "${{api.PRIVATE_URL}}"},
  {"name": "HOSTNAME", "value": "0.0.0.0"}]}' >/dev/null
```

Referências disponíveis:

| Referência | Valor |
|---|---|
| `${{api.PRIVATE_URL}}` | `http://api:8080` (nome e porta do serviço) |
| `${{api.PRIVATE_HOST}}`, `${{api.PORT}}` | `api` e `8080` |
| `${{web.PUBLIC_URL}}`, `${{web.PUBLIC_DOMAIN}}` | `https://<slug>.<domínio de apps>` e o domínio (vazios se o serviço é privado) |
| `${{db.DATABASE_URL}}`, `${{db.PGHOST}}`, `${{db.PGPORT}}`, `${{db.PGUSER}}`, `${{db.PGPASSWORD}}`, `${{db.PGDATABASE}}` | Postgres, com `sslmode=verify-full` |
| `${{mariadb.DATABASE_URL}}`, `…MYSQL_HOST/PORT/USER/PASSWORD/DATABASE` | MariaDB, com `ssl=true` |
| `${{jobs.LIBSQL_URL}}`, `${{jobs.LIBSQL_AUTH_TOKEN}}`, `${{jobs.DATABASE_URL}}` | SQLite (libSQL): `DATABASE_URL` é igual a `LIBSQL_URL` |
| `${{shared.NOME}}` | variável compartilhada do projeto |

Para escrever literalmente `${{` num valor, use `$${{`. Referências só enxergam o **próprio projeto**, aceitam aninhamento até 16 níveis e cada valor expandido tem até 64 KiB (ambiente total até 256 KiB). Mudar um valor referenciado marca os dependentes com `needs_redeploy`: faça deploy deles.

Confira o grafo: `GET /v1/projects/$P/services/$WORKER` traz `depends_on` (`["api","db","jobs"]` depois das variáveis) e `needs_redeploy`.

Erros: `403` (falta `env:write`), `400 invalid_request` (nome fora de `^[A-Za-z_][A-Za-z0-9_]{0,255}$`), `409 sensitive_lowered` (uma variável sensível nunca volta a não sensível).

### 5. Enviar o código e implantar, em ordem

Serviço `upload` só tem o que implantar depois de **receber um arquivo**, e o envio **é** o deploy do serviço (`multipart/form-data`, campo `file`, `.tar.gz` ou `.zip`, até 512 MB). Como o `worker` e o `web` referenciam a `api`, implante nesta ordem: `api`, depois `worker` e `web`. A `Idempotency-Key` abaixo inclui o hash do arquivo: reenviar o **mesmo** arquivo em 24 h repete o deploy anterior em vez de criar outro; para forçar de propósito, mude a chave.

```bash
# empacote sem lixo (sem .git, node_modules, .env)
tar --exclude=.git --exclude=node_modules --exclude=.env -czf /tmp/api.tgz    -C ./api .
tar --exclude=.git --exclude=node_modules --exclude=.env -czf /tmp/worker.tgz -C ./worker .
tar --exclude=.git --exclude=node_modules --exclude=.env -czf /tmp/web.tgz    -C ./web .

# envia SERVICO_ID ARQUIVO: dispara o deploy e imprime o id do deployment
envia() {
  curl -sS -X POST "$B/projects/$P/services/$1/deployments" -H "$H" \
    -H "Idempotency-Key: $R-up-$1-$(sha256sum "$2" | cut -c1-12)" -F "file=@$2" | jq -r .id
}

D=$(envia "$API" /tmp/api.tgz);    espera "$B/projects/$P/services/$API/deployments/$D"
D1=$(envia "$WORKER" /tmp/worker.tgz); D2=$(envia "$WEB" /tmp/web.tgz)
espera "$B/projects/$P/services/$WORKER/deployments/$D1"
espera "$B/projects/$P/services/$WEB/deployments/$D2"
```

Se `espera` falhar, **leia o motivo antes de tentar de novo** (passo 9 e [Tratamento de erros](#tratamento-de-erros)). Um deploy que termina `failed` não devolve erro HTTP.

### 6. Variante: imagens ou git, e deploy em grupo

Com fonte `image` ou `git`, não há passo de envio: o **deploy em grupo** sobe tudo na ordem certa com uma chamada. Para `image`, fixe por digest (`repo:tag@sha256:…`; veja [Imagem pública](/guia/imagem-publica/)). Para `git`, uma pessoa precisa ter instalado a integração GitHub no time e passar o `installation_id` ([Monorepo](/guia/monorepo/)).

O bloco abaixo é **executável de ponta a ponta** (cria um projeto de teste com a mesma topologia, usando imagens) e termina disparando o grupo:

```bash
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"; J="Content-Type: application/json"; B="$NEBULAR_API/v1"
P=$(curl -sS -X POST "$B/projects" -H "$H" -H "$J" -H "Idempotency-Key: dms-proj-$SUF" \
  -d "{\"name\": \"dms-$SUF\"}" | jq -r .id)
curl -sS -X POST "$B/projects/$P/databases" -H "$H" -H "$J" -H "Idempotency-Key: dms-db-$SUF" \
  -d '{"name": "db", "engine": "postgres", "quota_mb": 1024}' >/dev/null
curl -sS -X POST "$B/projects/$P/databases" -H "$H" -H "$J" -H "Idempotency-Key: dms-jobs-$SUF" \
  -d '{"name": "jobs", "engine": "sqlite", "quota_mb": 256}' >/dev/null
API=$(curl -sS -X POST "$B/projects/$P/services" -H "$H" -H "$J" -H "Idempotency-Key: dms-api-$SUF" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "port": 8080, "healthcheck_path": "/healthz",
       "source": {"type": "image", "ref": "ghcr.io/org/api:1.0"}}' | jq -r .id)
WORKER=$(curl -sS -X POST "$B/projects/$P/services" -H "$H" -H "$J" -H "Idempotency-Key: dms-worker-$SUF" \
  -d '{"name": "worker", "kind": "app", "visibility": "private", "port": 8081, "healthcheck_path": "/healthz",
       "source": {"type": "image", "ref": "ghcr.io/org/worker:1.0"}}' | jq -r .id)
WEB=$(curl -sS -X PATCH "$B/projects/$P/services/web" -H "$H" -H "$J" \
  -d "{\"visibility\": \"public\", \"slug\": \"dms-$SUF\", \"port\": 3000,
       \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/web:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$B/projects/$P/services/$API/variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "DATABASE_URL", "value": "${{db.DATABASE_URL}}", "sensitive": true}]}' >/dev/null
curl -sS -X PUT "$B/projects/$P/services/$WORKER/variables" -H "$H" -H "$J" -d '{"variables": [
  {"name": "DATABASE_URL", "value": "${{db.DATABASE_URL}}", "sensitive": true},
  {"name": "LIBSQL_URL", "value": "${{jobs.LIBSQL_URL}}"},
  {"name": "API_URL", "value": "${{api.PRIVATE_URL}}"}]}' >/dev/null
curl -sS -X PUT "$B/projects/$P/services/$WEB/variables/API_URL" -H "$H" -H "$J" \
  -d '{"value": "${{api.PRIVATE_URL}}"}' >/dev/null

curl -sS -X POST "$B/projects/$P/deploy" -H "$H" -H "$J" -H "Idempotency-Key: dms-grp-$SUF" -d '{}'
```
```json
{"id": "01j9zk0dst6zttk3bamcgshaxf", "project_id": "01j9zkk07fhzv5zsmn996cdwpb", "status": "running", "items": [{"service_id": "01j9zkff8y1dmcwa49fanx9qak", "deployment_id": "01j9zkxg2h4dbcfe129fwypfsb", "status": "queued", "layer": 0}]}
```

Como o grupo se comporta (do contrato da API e do orquestrador):

- **Ordem em camadas.** A camada N só começa quando a N-1 está `ready`. Dentro de uma camada, até 4 serviços em paralelo. Cada item traz `layer`.
- **Falha propaga.** Se um serviço falha, os que dependem dele ficam `blocked`; os que já estavam no ar continuam.
- **Serviço sem o que implantar** (por exemplo `upload` que nunca recebeu arquivo) vira item `skipped` com `reason`, e o grupo segue. Se **tudo** é `skipped`, o grupo termina `ready` sem implantar nada. Citar o serviço em `services` não o pula: sem fonte, o deploy dele falha.
- **Subconjunto.** `{"services": ["api", "web"]}` (ids ou nomes, até 100) implanta só esses; dependências fora da seleção são assumidas no ar.
- **Grupo novo substitui o grupo em andamento.** Um segundo `POST …/deploy` no mesmo projeto enquanto outro roda **cancela** o anterior (`superseded`; o que estava construindo termina `canceled`). Não dispare dois seguidos: espere o primeiro ou cancele.
- **Grupo com `upload`** reimplanta o **último arquivo enviado** de cada serviço. Serve para propagar mudança de variável; **código novo** exige enviar o arquivo de novo (passo 5).
- Nada é criado se houver referência inexistente ou ciclo: o `POST` responde `422` antes (`unresolved_reference`, `reference_cycle`, com `details.references`).
- Cada serviço do grupo consome 1 da cota `deploys_per_hour` do time.

### 7. Acompanhar o grupo

Um único `GET` mostra o grupo e cada serviço. `G` é o `id` devolvido pelo `POST …/deploy`. Não existe listagem de grupos: guarde o id.

```bash
G=$(curl -sS -X POST "$B/projects/$P/deploy" -H "$H" -H "$J" -H "Idempotency-Key: $R-grupo-1" -d '{}' | jq -r .id)

d=2
for i in $(seq 1 40); do
  S=$(curl -sS "$B/projects/$P/group-deployments/$G" -H "$H")
  echo "$S" | jq -r '"grupo \(.status): " + ([.items[] | "\(.service_id[-6:])=\(.status)"] | join(" "))'
  case "$(echo "$S" | jq -r .status)" in
    ready) break ;;
    failed|canceled|superseded) echo "$S" | jq '{status, error, items}' >&2; exit 1 ;;
  esac
  sleep "$d"; d=$(( d * 2 > 30 ? 30 : d * 2 ))
done
```

Estados do grupo: `running`, `ready`, `failed`, `canceled`, `superseded`. Estados dos itens: `queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `canceled`, `skipped`. Item `failed`: pegue o `deployment_id` e leia o log (passo 9). Para **cancelar** um grupo em andamento: `POST /v1/projects/{p}/group-deployments/{g}/cancel` (escopo `deploy`; grupo já terminado volta inalterado).

### 8. Domínios

Todo serviço `public` já tem `https://<slug>.<domínio de apps>` (campo `public_url`). Serviço `private` não aceita domínio (`400`). Para um domínio próprio, o agent cria o registro e a **pessoa** configura o DNS:

```bash
curl -sS -X POST "$B/projects/$P/services/$WEB/domains" -H "$H" -H "$J" -H "Idempotency-Key: $R-dominio" \
  -d '{"hostname": "pedidos.exemplo.com.br"}' | jq '{status, dns, verification}'
# a pessoa cria o CNAME/A e o TXT _nebular-verify.<host> no DNS (Cloudflare: "DNS only", nuvem cinza)
# depois: POST .../domains/{id}/verify (sem corpo) e polling em GET .../domains/{id} até status=active
```

Erros: `409 domain_taken`, `403` (falta `domains:write`), `422 rate_limited` no `verify` (espere `details.retry_after_seconds`). Detalhes: [Domínio próprio](/dominios/dominio-proprio/).

### 9. Verificar

```bash
URL=$(curl -sS "$B/projects/$P/services/$WEB" -H "$H" | jq -r .public_url)
curl -sS "$URL/status" | jq .
# esperado: api.db_reachable=true, api.uploads_writable=true, api.database_url_set=true
curl -sS "$B/projects/$P/services/$WORKER" -H "$H" | jq '{status, needs_redeploy, depends_on}'
```

Leia o que cada serviço escreveu em runtime (`logs:read`; valores sensíveis são mascarados):

```bash
curl -sS -G "$B/projects/$P/services/$API/logs" -H "$H" --data-urlencode "since=2026-10-11T00:00:00Z" | jq -r .text
curl -sS "$B/projects/$P/services/$API/deployments/$D/logs" -H "$H" | jq -r .text   # log de build
```

`GET /v1/projects/{p}/services/{s}` devolve `status` (`idle`, `deploying`, `running`, `failed`) e `needs_redeploy`. `worker` com `api_reachable=false` no `/status` quase sempre é a porta errada em `api` (`port` do serviço diferente da porta em que o processo escuta).

### 10. Nova versão e rollback

- **Código novo de um serviço:** envie o arquivo de novo (passo 5), sempre na ordem das dependências. Um deploy de serviço enquanto outro do **mesmo** serviço roda responde `409 deploy_in_progress`.
- **Só variável mudou:** `needs_redeploy` lista quem está defasado; dispare o grupo (`services` com os afetados) ou o deploy de cada um.
- **Rollback é por serviço, não existe rollback de grupo.** Liste os deploys, pegue um `ready` anterior e reimplante-o **com as variáveis daquela versão**:

```bash
curl -sS "$B/projects/$P/services/$API/deployments" -H "$H" | jq -r '.items[] | "\(.id)  \(.status)  \(.created_at)"'
curl -sS -X POST "$B/projects/$P/services/$API/deployments/$ANTERIOR/rollback" -H "$H" -H "$J" \
  -H "Idempotency-Key: $R-rb-$ANTERIOR" -d '{}'
```

Se a versão problemática mudou o contrato entre serviços, faça rollback também dos dependentes, na ordem inversa (`web` e `worker`, depois `api`). Rollback **não desfaz dados** nem migrations: veja [Migrações](/bancos/migracoes/). Erros: `409 nothing_to_rollback` (o destino não está `ready`), `409 deploy_in_progress`, `429 rate_limited` (conta na cota por hora).

## Tratamento de erros

Formato fixo: `{"error": "<codigo>", "message": "..."}`; decida pelo `error`. Tabela completa em [Tabela de erros](/erros/tabela/).

| Situação | Código | O que fazer |
|---|---|---|
| Token ausente, expirado ou revogado | `401 unauthorized` | **Pare.** Peça token novo a uma pessoa. |
| Falta escopo, ou token restrito a projetos criando projeto | `403 forbidden` | **Pare.** Diga qual escopo falta (tabela dos pré-requisitos). |
| Recurso inexistente ou de outro time | `404 not_found` | Confira o id listando com `GET`. Não varie ids. |
| Nome ou slug repetido | `409 name_taken`, `409 slug_taken` | Escolha outro nome. |
| Limite de projetos do time | `409 project_quota_exceeded` | **Pare** e avise a pessoa. |
| Limite de serviços, bancos ou volume do plano | `422 quota_exceeded` | **Pare** e avise; consulte `GET /v1/limits`. |
| Referência para algo que não existe / ciclo | `422 unresolved_reference` / `reference_cycle` (`details.references`) | Corrija as variáveis e dispare de novo. Nada foi criado. Com banco ainda `provisioning` a resolução também falha (o erro exato pode variar): espere `ready` antes do deploy. |
| Valor expandido grande demais, referência profunda, sintaxe inválida | `422 value_too_large` / `reference_too_deep` / `invalid_reference` | Reduza ou corrija. |
| Já há deploy do serviço rodando | `409 deploy_in_progress` | Acompanhe o deploy em curso; não dispare outro. |
| Mesma `Idempotency-Key` com outro corpo | `422 idempotency_conflict` | Gere chave nova. |
| Corpo com `Content-Type` errado | `415 unsupported_media_type` | JSON com `application/json`; upload com `multipart/form-data`. |
| Rate limit, ou `deploys_per_hour` do plano | `429 rate_limited` | Espere `Retry-After` segundos e repita. |
| Armazenamento de build indisponível | `503 unavailable` com `details.error_code` = `build_storage_unavailable` (ou `build_disk_full`) e `details.deployment_id` | Um deploy `failed` ficou no histórico. Repita em alguns minutos; persistindo, **pare** e avise. |
| Banco ou nó indisponível | `503 unavailable` | Repita com backoff (5, 10, 20, 40 s). |

### Quando o deploy termina `failed` (sem erro HTTP)

Leia `GET …/deployments/{d}`: `error.code` e `error.message`. Depois o log de build (`…/deployments/{d}/logs`) e o de runtime (`…/services/{s}/logs`).

| `error.code` | Causa | Correção |
|---|---|---|
| `activate_readonly_write` | o app tentou gravar sob `/app` (somente leitura) | Grave em `/tmp` ou monte um volume na subpasta (`PUT …/volume` com `mount_path: "/app/<pasta>"`) e redeploy. |
| `activate_no_http` | o processo roda mas não responde HTTP na `port` do serviço | Escute em `0.0.0.0:$PORT`; worker também precisa de um `/healthz`; confira `port` e `healthcheck_path`. |
| `activate_app_crashed`, `crashed_after_start` | o app encerra logo ao iniciar | Leia a primeira linha de erro na `message` e no log de runtime (variável faltando, banco recusando conexão). |
| `image_requires_root` | a imagem exige root | Declare `build.user` (`uid[:gid]`, nunca root) no serviço ou troque a imagem. |
| `unresolved_reference`, `reference_cycle` | a referência só falhou no build | Corrija as variáveis. |
| `build_oom`, `build_timeout` | build sem memória ou lento demais | Reduza o build ou aumente `resources`. |
| `build_storage_error`, `build_disk_full`, `build_storage_unavailable` | problema de armazenamento da plataforma, não do seu código | Repita em alguns minutos; persistindo, avise a pessoa. |
| `team_app_limit` | o time já roda o máximo de apps do plano (`message`: "limite de apps em execução do time atingido (N de M)...") | **Pare**: peça à pessoa para parar/remover um app ou ampliar o limite. Repetir não adianta. |
| `deploy_failed` (genérico) | outra falha | Leia a `message`. |

Regra de ouro: máximo de 3 tentativas por serviço, **mudando algo** a cada uma. Repetir o mesmo envio sem corrigir a causa só gasta a cota por hora.

## Idempotência

Todo `POST` que cria ou dispara aceita `Idempotency-Key` (8 a 128 caracteres de `[A-Za-z0-9._:-]`). Mesma chave e mesmo pedido em 24 h devolvem a mesma resposta com `Idempotent-Replay: true`; mesma chave com pedido diferente dá `422 idempotency_conflict`; chave malformada dá `400`. Só respostas de sucesso são gravadas, então repetir após uma falha executa de verdade. Padrão recomendado: `"$R-<recurso>"` com um `R` único por execução do plano, para que reexecutar o script inteiro após uma queda não duplique serviços nem deploys. `PUT` (variáveis, volume) e `PATCH` já são naturalmente repetíveis.

## Boas práticas

- **Segredos.** Nunca imprima, registre ou cole valores de variáveis sensíveis, credenciais de banco ou o token. Entregue segredo ao app **por variável** (de preferência por referência, como `${{db.DATABASE_URL}}`), nunca no código, na imagem ou em `NEXT_PUBLIC_*` (que vai para o bundle do browser). Marque `sensitive: true`.
- **Credenciais só com a pessoa.** `POST …/databases/{s}/credentials` e `env:reveal` exigem confirmação de identidade (step-up). Não os peça nem contorne: o app não precisa deles, a plataforma injeta as variáveis no deploy.
- **Disco.** O sistema de arquivos do app é somente leitura. Temporários em `/tmp` (64 MB, em memória, some a cada restart). Dados que precisam sobreviver: volume em subpasta de `/app` (`/app/uploads`, `/app/data`), 1 por serviço, 1 a 50 GB, que **sobrevive a redeploy**. `/app` inteiro, `/app/.next` e `/app/.next/cache` não podem ser volume (o cache do Next já é um tmpfs da plataforma). Banco de dados de verdade vai em banco gerenciado, não em arquivo no volume.
- **Rede.** Fale com outro serviço pelo nome (`${{api.PRIVATE_URL}}`). No Next.js, chame a `api` no servidor (route handler ou server component), nunca do browser. Deixe `private` tudo o que não precisa de URL pública.
- **Saúde.** Todo serviço, inclusive worker, escuta em `0.0.0.0:$PORT` e responde 2xx/3xx em `healthcheck_path`. Sem isso o deploy termina `failed`.
- **Agendamento.** Não há cron para serviços do time. Rode o agendador dentro do worker (`setInterval`, biblioteca de cron) ou chame um endpoint público de um agendador externo.
- **Ordem.** Bancos `ready`, depois `api`, depois quem depende dela. Deploy em grupo cuida da ordem entre apps; bancos você espera com `GET`.
- **Cota.** Antes de começar leia `GET /v1/limits`; cada deploy de cada serviço, rollback e grupo conta em `deploys_per_hour`.
- **Destrutivo.** Apagar projeto, serviço, volume, banco ou domínio só com ordem explícita da pessoa. Ordem de remoção: volume antes do serviço (`409 volume_attached`); banco com backup final por padrão (`final_backup: true`); apagar projeto remove tudo e é irreversível. Com token, o escopo é a única barreira: a confirmação tem de vir da pessoa.
- **Limpeza de testes.** Se criou um projeto só para teste, apague-o ao final (com autorização), para não consumir a cota do time.

## O que não é suportado

- **Manifesto declarativo.** Não há arquivo único que descreva a aplicação.
- **Réplicas e escala horizontal.** Um container por serviço; sem autoscale, sem balanceador entre instâncias, sem `replicas`.
- **Zero downtime não é garantia de réplica:** a troca de versão sobe o container novo, move o nome privado e aposenta o antigo depois de um período de drenagem, mas há uma única instância servindo.
- **Tipos `worker` e `cron`.** Só `app` e `database`. Sem agendador de tarefas para serviços do time (o agendador interno existe apenas dentro de templates da plataforma).
- **Templates do time.** O catálogo (`GET /v1/templates`) é da plataforma, embutido no servidor, hoje só `wordpress`; aceita só imagens fixadas por digest. Não é possível publicar um template multi-serviço próprio.
- **Rollback de grupo**, **dry-run/plan** do deploy, **listagem de deploys de grupo** e **webhooks de deploy**: não existem. Acompanhe por polling.
- **Mais de um volume por serviço**, volume compartilhado entre serviços, ou mais de uma porta por serviço.
- **Serviço sem HTTP.** Todo serviço de aplicação é validado por HTTP na porta declarada.
- **Banco acessível de fora da plataforma** (notebook, outro provedor): só os serviços do projeto conseguem conectar.
- **E-mail por SMTP direto** (bloqueado; use um provedor por API HTTPS).
- **Comunicação entre projetos.** Cada projeto é uma rede isolada.

## Manifesto declarativo: não existe ainda

Hoje o "manifesto" é o roteiro de chamadas acima. Se o time precisar repetir a topologia (por exemplo, criar um ambiente de teste igual ao de produção), guarde o **script do passo a passo** no repositório do app e reexecute-o com outro `R`. Este guia não promete data nem formato para um arquivo declarativo.

## Ver também

[Front, back e banco](/conectados/front-back-db/), [Variáveis e referências](/conectados/variaveis-e-referencias/), [Rede privada](/conectados/rede-privada/), [Volumes](/conectados/volumes/), [Deploys e status](/operacao/deploys-e-status/), [Rollback](/operacao/rollback/), [Limites e cotas](/operacao/limites-e-cotas/), [Escala e recursos](/operacao/escala-e-recursos/), [Tabela de erros](/erros/tabela/), [Monorepo](/guia/monorepo/).

---

URL: https://docs.nebularws.com/agents/corrigir-deploy.md

# Como corrigir cada erro de deploy (cookbook)

**Esta página é o destino do `fix_url` de cada erro de deploy.** Cada `error_code` tem uma seção com âncora estável: o `fix_url` de um erro `activate_readonly_write` aponta para `#activate_readonly_write` aqui. Chegue direto pela âncora, leia **o que significa**, aplique **como corrigir** e confira **de quem é a culpa** (código do app ou configuração da plataforma).

Antes de mexer no código, leia o log de build e o log do container ([Logs](/operacao/logs/)) — o `error_code` diz a categoria, o log diz a causa exata. Para a tabela completa com HTTP e ação (repetir/corrigir/parar), veja [Tabela de erros](/erros/tabela/); para o passo a passo de diagnóstico, [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/); para as regras normativas do app, [Contrato de App Nebular](/agents/contrato-app/).

:::note[Como ler as âncoras]
O id de cada seção é **exatamente** o `error_code` (ex.: `## activate_oom` gera a âncora `#activate_oom`). Alguns códigos de build também respondem pelo nome canônico com prefixo `build_` (ex.: `#install_failed` e `#build_install_failed` levam à mesma seção).
:::

## Erros de ativação (o app subiu e não ficou de pé)

O build terminou e a plataforma tentou **ativar** o container; ele não respondeu como esperado. Quase sempre é código ou configuração do app.

### activate_no_http

**O que significa:** o app está rodando e estável, mas não respondeu HTTP na porta esperada dentro da janela de ativação.

**Como corrigir:**

1. Escute em `0.0.0.0:$PORT` (a Nebular injeta `PORT`), **nunca** em `127.0.0.1`, `localhost` ou porta fixa. Portas abaixo de 1024 não existem no runtime.
2. Garanta que a `port` declarada no serviço é a mesma em que o app escuta.
3. Abra a porta **antes** de qualquer trabalho pesado (migration, aquecimento de cache, chamada a terceiros).
4. Confira o `healthcheck_path`: ele precisa responder `2xx`/`3xx` sem efeitos colaterais. Se devolve `4xx`/`5xx`, o app conta como sem HTTP.

**Culpa:** código do app. Detalhe em [Contrato de App](/agents/contrato-app/) e [App pronto para escalar](/operacao/app-pronto-para-escalar/).

### activate_readonly_write

**O que significa:** o app tentou gravar num caminho somente-leitura. A raiz e `/app` não aceitam escrita; só volume montado ou `/tmp`/`$TMPDIR` (64 MB, em memória, apagado a cada deploy).

**Como corrigir:**

1. Descubra o caminho que o app quis gravar (a mensagem do erro traz o caminho; o log do container confirma).
2. Se é dado **temporário**, aponte-o para `/tmp` ou `$TMPDIR`.
3. Se é dado que **precisa sobreviver ao deploy** (banco SQLite, uploads, índice), monte um [volume](/conectados/volumes/) nesse caminho e leia o caminho de uma variável de ambiente (`DB_FILE`, `DATA_DIR`), nunca fixo no código.
4. Se o arquivo pode ser **gerado no build** (assets, bundle), gere-o no build, não no boot.

**Banco SQLite gravando em disco somente-leitura?** Em vez de um volume, considere mover o banco para um [banco gerenciado libSQL](#migrar-sqlite-local-para-gerenciado) — recomendado para apps sem estado que escalam. A plataforma também pode ter registrado uma [sugestão de persistência](/conectados/sugestoes-de-persistencia/) para este caso.

**Culpa:** código do app (gravação em caminho errado), resolvida com um recurso da plataforma (volume) ou mudança para banco gerenciado.

### activate_app_crashed

**O que significa:** o app encerrou logo depois de iniciar. A mensagem do erro traz a primeira linha de erro do log.

**Como corrigir:**

1. Leia o log do container ([Logs](/operacao/logs/)) — a causa quase sempre está na primeira linha de erro.
2. As causas mais comuns, em ordem:
   - **Variável de ambiente faltando.** Defina as envs do serviço; o app deve **falhar no boot com mensagem clara** quando falta algo crítico, não cair em silêncio.
   - **Arquivo ausente** (config, template, binário que não saiu no lugar certo).
   - **Escrita em disco somente-leitura** no boot → trate como [`activate_readonly_write`](#activate_readonly_write).
   - **Conexão recusada a um banco** (`connection refused` numa porta de banco) → o serviço não tem banco ligado; ligue por referência (`DATABASE_URL = ${{db.DATABASE_URL}}`, veja [Conexão e referências](/bancos/conexao-e-referencias/)) ou, para SQLite, migre para [libSQL gerenciado](#migrar-sqlite-local-para-gerenciado).
3. Corrija a causa e dispare novo deploy. A versão anterior continua no ar enquanto isso.

**Culpa:** código ou configuração do app. Quando o log mostra tentativa de criar/gravar o arquivo de banco em disco somente-leitura, trate como falta de persistência (volume ou banco gerenciado).

### activate_oom

**O que significa:** o app usou mais memória que o limite do serviço e foi encerrado (OOM) no runtime.

**Como corrigir:**

1. Reduza o consumo: diminua caches em memória, concorrência, tamanho de pool e workers.
2. Procure vazamentos (memória que só cresce) no log e nas métricas.
3. Se o consumo é legítimo, suba `resources.memory_mb` do serviço ou troque de plano ([Escala e recursos](/operacao/escala-e-recursos/)).

**Culpa:** código do app (consumo) ou configuração (limite baixo demais para a carga real).

### image_requires_root

**O que significa:** a imagem declara ou assume `USER root`. A plataforma a força a rodar como `65534` (não-root) e o container encerrou nos primeiros 30 s.

**Como corrigir:**

1. Declare `build.user` no serviço (`uid[:gid]`, **nunca** root) com um usuário que a imagem suporte.
2. Ou troque por uma variante da imagem sem privilégio (muitas imagens oficiais têm tag `-nonroot`/`-slim` com usuário não-root).
3. Garanta que os diretórios que o app escreve pertencem a esse usuário (ou são volume/`/tmp`).

**Culpa:** código do app / imagem. A plataforma não roda container como root por política de isolamento ([Isolamento](/seguranca/isolamento/)).

## Erros de build (o artefato não foi produzido)

A falha aconteceu **antes** de ativar: ao clonar, detectar a stack, instalar, compilar ou copiar o artefato. Leia sempre o log de build primeiro.

### build_clone_failed

**O que significa:** a plataforma não conseguiu clonar o repositório.

**Como corrigir:**

1. Confira o repositório e a branch configurados no serviço.
2. Confira a instalação do GitHub App no serviço (acesso ao repositório pode ter sido revogado).
3. Em repositório privado, confirme que a instalação cobre aquele repositório.

**Culpa:** configuração (acesso/repo/branch), raramente do app.

### detect_failed

<span id="build_detect_failed"></span>

**O que significa:** a plataforma não conseguiu detectar automaticamente a stack do app (qual builder usar).

**Como corrigir:**

1. Declare `build.builder` explicitamente no serviço (ex.: `nixpacks`, `dockerfile`) em vez de depender da detecção.
2. Em monorepo, defina o `root_dir` correto para a plataforma olhar a pasta certa ([Monorepo](/guia/monorepo/)).
3. Confirme que os arquivos-sinal da stack existem na raiz do build (`package.json`, `go.mod`, `requirements.txt`, `Dockerfile`…).

**Culpa:** configuração (builder/`root_dir` não declarados).

### install_failed

<span id="build_install_failed"></span>

**O que significa:** a instalação de dependências falhou (o gerenciador de pacotes retornou erro).

**Como corrigir:**

1. Leia o log de build: ele traz a dependência e o motivo (versão inexistente, rede, conflito de resolução).
2. **Fixe versões** e comite o lockfile (`package-lock.json`, `go.sum`, `Cargo.lock`, `poetry.lock`) — build não deve resolver "latest".
3. Remova dependências que exigem rede fora do registro padrão ou toolchain que não está na imagem de build.

**Culpa:** código do app (dependências/lockfile). Se a falha é claramente de rede transitória, repita o deploy.

### script_failed

<span id="build_script_failed"></span>

**O que significa:** o comando de build (compilar/empacotar) retornou código diferente de 0.

**Como corrigir:**

1. Reproduza o build localmente com o mesmo comando; corrija o erro de compilação/empacotamento.
2. Se o comando detectado não é o que você quer, declare `build_command` explicitamente no serviço.
3. Garanta que o artefato sai no caminho esperado (em Go, o binário **deve** sair em `/app/app`; veja [Go](/guia/go/)).

**Culpa:** código do app (erro de build) ou configuração (`build_command` errado).

### build_copy_failed

**O que significa:** a plataforma não conseguiu copiar o artefato produzido para a imagem final — em geral o artefato não está onde ela espera.

**Como corrigir:**

1. Confirme o caminho de saída do artefato (binário/bundle) e alinhe-o ao esperado (ex.: `/app/app` em Go).
2. Em monorepo, confira `root_dir` e os caminhos relativos do `build_command`.
3. Verifique que o build realmente gerou o arquivo (um `build_command` que "passa" sem produzir saída cai aqui).

**Culpa:** código do app / configuração (caminho de saída).

### build_failed

**O que significa:** falha genérica de build quando a plataforma não classificou uma fase específica. Trate como "leia o log e isole a fase".

**Como corrigir:**

1. Leia o log de build de cima para baixo: a primeira linha de erro aponta a fase real (clone, detect, install, script, copy).
2. Vá para a seção específica desta página conforme a fase ([install_failed](#install_failed), [script_failed](#script_failed), [detect_failed](#detect_failed), [build_copy_failed](#build_copy_failed), [build_clone_failed](#build_clone_failed)).
3. Se nenhuma fase se encaixa e o app está correto, não é culpa do app — reporte o `error_code`, o `id` do deploy e a hora.

**Culpa:** depende da fase que o log revela.

### oom

<span id="build_oom"></span>

**O que significa:** o build estourou a memória disponível e foi encerrado (distinto de [`activate_oom`](#activate_oom), que é no runtime).

**Como corrigir:**

1. Reduza o paralelismo do build (ex.: `-j1`/`--max-old-space-size` menor, menos workers).
2. Tire etapas pesadas do build (geração de assets gigantes, testes no build).
3. Reduza o que entra no artefato (`.dockerignore`, menos dependências de build).

**Culpa:** código do app (build pesado).

### timeout

<span id="build_timeout"></span>

**O que significa:** o build passou do tempo máximo permitido.

**Como corrigir:**

1. Enxugue o build: cache de dependências via lockfile, menos etapas, nada de download gigante a cada build.
2. Tire testes e tarefas longas do caminho de build.
3. Em multi-stage, remova estágios que não contribuem para a imagem final.

**Culpa:** código do app (build longo).

### disk_full

<span id="build_disk_full"></span>

**O que significa:** o espaço de build encheu durante a produção do artefato.

**Como corrigir:**

1. Reduza o tamanho do artefato e dos intermediários (multi-stage descartando camadas de build, `.dockerignore`, limpeza de caches no mesmo passo que os cria).
2. Evite copiar `node_modules`/alvos de build para a imagem final.
3. Se o artefato já é enxuto e o erro persiste, **não é culpa do app**: é falta de espaço na plataforma (aparentada de `build_storage_unavailable`). Reporte o `error_code`, o `id` do deploy e a hora.

**Culpa:** código do app (artefato grande) na maioria dos casos; plataforma quando o artefato é enxuto e o erro persiste.

## Erros de referência entre variáveis (`${{svc.VAR}}`, `${{shared.VAR}}`)

As referências são resolvidas **no deploy**: o `POST` do deploy responde `422` com `details.references` (apenas nomes, nunca valores) e **nada é criado**. Corrija e refaça o deploy. Detalhe em [Variáveis e referências](/conectados/variaveis-e-referencias/).

### unresolved_reference

**O que significa:** a referência aponta para uma variável ou serviço que não existe. A lista `details.references` diz quais.

**Como corrigir:**

1. Para cada nome na lista, crie a variável ou o serviço citado, ou corrija o nome na referência.
2. Se a referência aponta para um **banco que não existe**, crie o [banco gerenciado](/bancos/postgres/) e ligue por `${{<db>.DATABASE_URL}}` (a plataforma pode ter registrado uma [sugestão](/conectados/sugestoes-de-persistencia/)).
3. Refaça o deploy.

**Culpa:** configuração do app (referência para algo que falta).

### reference_cycle

**O que significa:** há um ciclo — `A` referencia `B` que referencia `A` (direta ou indiretamente).

**Como corrigir:**

1. Siga a cadeia em `details.references` e identifique o laço.
2. Quebre o ciclo usando um **valor literal** em um dos lados em vez da referência.
3. Refaça o deploy.

**Culpa:** configuração do app.

### invalid_reference

**O que significa:** um `${{...}}` está fora da forma `escopo.VAR` (sintaxe inválida).

**Como corrigir:**

1. Use exatamente `${{<serviço>.VAR}}` ou `${{shared.VAR}}` — sem espaços estranhos, sem escopo vazio, sem `.` a mais.
2. Confira a grafia do nome do serviço e da variável.
3. Refaça o deploy.

**Culpa:** configuração do app (sintaxe).

### reference_too_deep

**O que significa:** a cadeia de referências tem mais de 16 níveis (uma variável que referencia outra, que referencia outra…).

**Como corrigir:**

1. Achate a cadeia: faça as variáveis apontarem direto para o valor final em vez de encadear.
2. Substitua os níveis intermediários por valores literais onde fizer sentido.
3. Refaça o deploy.

**Culpa:** configuração do app (encadeamento excessivo).

### value_too_large

**O que significa:** o valor expandido passou de 64 KiB, ou o ambiente total do serviço passou de 256 KiB.

**Como corrigir:**

1. Reduza o valor: não guarde arquivos, certificados grandes ou blobs em variável de ambiente.
2. Mova conteúdo grande para um [volume](/conectados/volumes/) ou um arquivo gerado no build e aponte a variável para o caminho.
3. Refaça o deploy.

**Culpa:** configuração do app (valor grande demais).

## Outros códigos (contexto)

Não têm âncora de remédio porque a ação é "esperar" ou "reportar", não corrigir o app:

- `team_app_limit`: o time já roda o máximo de apps do plano (a mensagem traz "N de M"). Pare ou remova um app, ou peça ao operador para ampliar o limite; depois repita.
- `build_storage_error`, `build_storage_unavailable`, `build_volume_unavailable`: falha interna de armazenamento de build da **plataforma** (não do seu repo). Repita em alguns minutos; se persistir, reporte.
- `deploy_failed`: genérico sem fase classificada — leia o log e caia na seção específica.
- `blocked`, `canceled`, `superseded`: estados de deploy, não falhas do app — veja [Deploys e status](/operacao/deploys-e-status/).

---

## Migrar SQLite local para banco gerenciado (libSQL)

<span id="migrar-sqlite-local-para-gerenciado"></span>

Quando o erro é [`activate_readonly_write`](#activate_readonly_write) ou [`activate_app_crashed`](#activate_app_crashed) **com o log mostrando tentativa de criar/gravar um arquivo de banco** (`.db`, `.sqlite`) em disco somente-leitura, você tem duas saídas: montar um [volume](/conectados/volumes/) (mantém o SQLite em arquivo) ou **migrar para libSQL gerenciado** (recomendado para apps sem estado que escalam em mais de uma réplica). Esta seção é o caminho de libSQL, já aplicado em 5 apps.

### Regra única (o app decide o modo no boot)

Se `LIBSQL_URL` — ou `DATABASE_URL` começando com `libsql://`, `https://` ou `wss://` — estiver definido, use o **banco remoto** com `LIBSQL_AUTH_TOKEN`. Sem isso, **caia no arquivo local** (fallback). Logue no boot **qual modo está ativo**, sem imprimir o token nem a URL.

### Passos na Nebular

1. **No deploy que falhou, aceite a sugestão de banco** (ou ligue o modo "presumir tudo" para a plataforma criar e ligar o recurso sugerido sem perguntar a cada passo). Veja [Sugestões de persistência](/conectados/sugestoes-de-persistencia/).
2. **Confirme que as variáveis foram injetadas** no serviço: `LIBSQL_URL`, `DATABASE_URL` e `LIBSQL_AUTH_TOKEN`. São **sensíveis** — tratadas como segredo, nunca em `NEXT_PUBLIC_*`/`VITE_*` nem em log.
3. **Defina as demais envs do app** (ex.: `ENV`, `TOTP_KEY`, `PUBLIC_BASE_URL`) com defaults seguros; falhe no boot se faltar algo crítico.
4. **Escute em `0.0.0.0:$PORT`.** A Nebular injeta `PORT`; por exemplo `LISTEN_ADDR=0.0.0.0:8080`. Nunca `127.0.0.1`/`localhost`.
5. **Redeploy.** O novo deploy sobe já falando com o banco remoto; o log do boot deve dizer "modo: libSQL remoto".

### Exemplo de cliente — Go (`libsql-client-go`, com fallback `modernc`)

É código do **seu app** (não é chamada à API `/v1` da Nebular):

```go
// abrirBanco escolhe o modo pelo ambiente: se há LIBSQL_URL (ou DATABASE_URL
// remoto), abre o banco gerenciado; senão cai no arquivo local. Chamada uma vez
// no boot, antes de abrir a porta HTTP.
func abrirBanco() (*sql.DB, error) {
	url := primeiroNaoVazio(os.Getenv("LIBSQL_URL"), os.Getenv("DATABASE_URL"))
	if ehRemoto(url) { // libsql:// | https:// | wss://
		token := os.Getenv("LIBSQL_AUTH_TOKEN")
		dsn := url + "?authToken=" + token
		log.Println("banco modo=libSQL-remoto") // nunca logar url/token
		return sql.Open("libsql", dsn)           // github.com/tursodatabase/libsql-client-go
	}
	caminho := primeiroNaoVazio(os.Getenv("DB_FILE"), "/tmp/app.db")
	log.Printf("banco modo=arquivo-local path=%s", caminho)
	return sql.Open("sqlite", caminho) // modernc.org/sqlite, sem CGO
}
```

### Exemplo de cliente — Node (`@libsql/client` no lugar de `better-sqlite3`)

```js
// criarCliente escolhe o modo pelo ambiente e devolve um cliente @libsql/client.
// Chamada no boot; o mesmo cliente serve arquivo local e banco remoto.
import { createClient } from "@libsql/client";

export function criarCliente() {
  const url = process.env.LIBSQL_URL || process.env.DATABASE_URL || "";
  const remoto = /^(libsql|https|wss):\/\//.test(url);
  if (remoto) {
    console.log("banco modo=libSQL-remoto"); // nunca logar url/token
    return createClient({ url, authToken: process.env.LIBSQL_AUTH_TOKEN });
  }
  const file = process.env.DB_FILE || "/tmp/app.db";
  console.log(`banco modo=arquivo-local path=${file}`);
  return createClient({ url: `file:${file}` });
}
```

### Avisos

- **Dados já gravados no arquivo local NÃO migram sozinhos** para o remoto. Exporte e importe o conteúdo explicitamente (dump do SQLite → carga no libSQL) antes de depender só do remoto.
- **Valide o que não vem de graça no remoto:** migrations aplicadas, triggers, índices e **FTS5** recriados, e `PRAGMA foreign_keys = ON` por conexão (não é herdado do arquivo local).
- Mantenha o **fallback local** funcionando para desenvolvimento e teste: sem `LIBSQL_URL`, o app continua subindo contra um arquivo em `/tmp` ou num [volume](/conectados/volumes/).

---

## Veja também

- [Contrato de App Nebular](/agents/contrato-app/) — as regras normativas cuja violação gera estes erros.
- [Sugestões de persistência](/conectados/sugestoes-de-persistencia/) — como a plataforma detecta falta de volume/banco e oferece criar.
- [Tabela de erros](/erros/tabela/) · [Fluxo de diagnóstico](/erros/fluxo-de-diagnostico/) · [Deploys e status](/operacao/deploys-e-status/) · [Logs](/operacao/logs/).