Identifica a conta e devolve os escopos do token usado.

A única rota que não exige escopo — basta o token valer. Devolve o id do token, nunca o valor nem o prefixo: quem chama já tem o segredo na mão, e ecoá-lo só o colocaria em mais um log.

{
  "status": "success",
  "response": {
    "account": { "id": "local_8ebf…", "name": "Maria", "email": "[email protected]" },
    "token": { "id": "tok_01H…", "scopes": ["apps:read", "apps:write"] }
  }
}

Plano, limites e uso da conta, numa chamada só.

Limites e uso já somados, na mesma resposta — é a mesma conta que a plataforma usa para aceitar ou recusar um deploy, então o que ela diz que cabe é o que ela deixa criar. Continua respondendo com a conta suspensa.

{
  "status": "success",
  "response": {
    "plan": { "type": "standard", "label": "Standard", "billingStatus": "active", "expiresAt": "2026-10-01T00:00:00.000Z" },
    "usage": {
      "ram":          { "limit": 4096, "used": 1536, "available": 2560 },
      "applications": { "limit": 16, "used": 3 },
      "databases":    { "limit": 4, "used": 1 },
      "blob":         { "limit": 5120, "used": 210, "available": 4910, "files": 42 }
    },
    "breakdown": { "bots": [], "websites": [], "databases": [] }
  }
}

Os workspaces da conta e os que compartilharam com ela.

Um workspace não passa a ser dono de nada: a aplicação continua pertencendo a quem a criou, e é o plano dele que a paga. O que o workspace acrescenta é quem mais a alcança. Convite pendente não aparece aqui — quem ainda não aceitou não enxerga o workspace.

{
  "status": "success",
  "response": {
    "workspaces": [
      { "id": "3f1c…", "name": "Equipe de produto", "owner": true, "role": "owner", "members": 3, "apps": 2, "createdAt": "2026-09-01T12:00:00.000Z" }
    ]
  }
}

Cria um workspace vazio.

O detalhe: as pessoas e as aplicações compartilhadas.

{
  "status": "success",
  "response": {
    "id": "3f1c…", "name": "Equipe de produto", "owner": true, "role": "owner",
    "members": [
      { "id": "9a2b…", "email": "[email protected]", "name": "Maria", "role": "member", "pending": false, "acceptedAt": "2026-09-02T10:00:00.000Z" }
    ],
    "apps": [
      { "id": "app_7c1…", "name": "checkout", "type": "website", "addedAt": "2026-09-01T12:30:00.000Z" }
    ]
  }
}

Renomeia o workspace.

Apaga o workspace. Só o dono.

As aplicações não são apagadas: elas continuam da conta que as criou, e apenas deixam de ser alcançáveis por quem estava no workspace.

As aplicações que este workspace compartilha.

Coloca uma aplicação no workspace.

Só aplicação da própria conta. Um administrador de workspace não repassa adiante uma aplicação que apenas lhe foi emprestada — isso tiraria do dono original o controle de quem alcança a aplicação dele, sem que ele ficasse sabendo.

Tira a aplicação do workspace.

Quem está no workspace, e com que papel.

pending: true é convite emitido e não aceito — e não alcança aplicação nenhuma. O acesso passa a existir no aceite, não no convite.

Convida pelo e-mail cadastrado, e manda o link por e-mail.

O e-mail precisa já ter conta na plataforma: um endereço desconhecido responde USER_NOT_FOUND e nada é criado. A pessoa recebe um link de uso único, válido por 7 dias, e o acesso só existe depois que ela o abre — aceitar é ato do titular e por isso não tem rota na API pública.

Limite: 20 por minuto: cada chamada manda um e-mail.

Troca o papel de quem já está no workspace.

Remove alguém do workspace.

O acesso cai na requisição seguinte: não há cache de associação, justamente para que revogar signifique revogar.

Lista as aplicações da conta com o estado atual de cada uma.

É a lista que responde “o que está no ar agora”, com o consumo do momento. Aplicação parada sai com running: false e sem números.

{
  "status": "success",
  "response": [
    { "id": "app_01H…", "running": true, "ram": "128.44MB", "cpu": "0.6%" },
    { "id": "app_01J…", "running": false }
  ]
}

Cria uma aplicação a partir de um pacote .zip.

multipart/form-data, com o arquivo e os campos de texto antes dele no corpo — é assim que o multipart os expõe. Os campos têm precedência sobre o arquivo de configuração do pacote, que é o que permite um zip sem configuração virar aplicação.

A resposta vem assim que a aplicação é criada e o pacote é aceito. O build continua depois disso — acompanhe por /deploys, que diz em que passo ele está e como terminou.

Cria uma aplicação direto de um repositório do GitHub.

Exige a conta do GitHub conectada em Conexões. Com autoDeploy, cada push na branch escolhida dispara um deploy novo.

Dados cadastrais da aplicação.

status aqui é o estado da linha — provisioning enquanto o build acontece, failed quando ele não passou —, e não o do container. Para o container, use /status.

{
  "status": "success",
  "response": {
    "id": "app_01H…", "name": "api-loja", "desc": null,
    "cluster": "node-3", "ram": 512, "language": "javascript",
    "status": "running", "type": "website",
    "domain": "loja.web.nexcloud.gg"
  }
}

Altera nome, descrição e autorestart.

Domínio próprio não entra aqui: ele tem ciclo de vida próprio e rotas próprias — daí o USE_DOMAINS_ENDPOINT.

Apaga a aplicação.

O container morre e a cota é liberada; a linha fica marcada como apagada, com a data, quem pediu e o motivo. As snapshots vão junto.

Consumo do container agora.

{
  "status": "success",
  "response": {
    "cpu": "0.60%", "ram": "128.44MB", "status": "running", "running": true,
    "storage": "24.10MB",
    "network": { "total": "1.20MB ↑ 8.40MB ↓", "now": "0B ↑ 2.10KB ↓" },
    "uptime": 864000
  }
}

Série de CPU, memória, rede e disco.

{
  "status": "success",
  "response": {
    "range": "1h",
    "sampleIntervalMs": 60000,
    "samples": [ { "t": 1788000000000, "cpu": 0.6, "ram": 128.4, "netTotal": 8400000, "netNow": 2100 } ]
  }
}

Container parado não rende amostra — registrar zero diria que ele rodou sem consumir nada, em vez de que não rodou.

Se a aplicação está respondendo, e por qual caminho isso foi verificado.

As linhas recentes do console da aplicação.

Os dias que têm log guardado.

Chame antes de pedir o histórico: é a lista de datas válidas.

{ "status": "success", "response": { "days": ["2026-09-01", "2026-08-31"] } }

O log de um dia, com os eventos daquele dia intercalados.

O que aconteceu com a aplicação, do mais recente.

As tentativas de subir código, com passos e desfecho.

Guardado por 90 dias. Cada linha diz de onde veio (upload, github, redeploy), quem pediu, quanto demorou e em que passo parou — é a primeira coisa a olhar quando algo não subiu.

{
  "status": "success",
  "response": {
    "deploys": [{
      "id": "dep_01H…", "kind": "app", "origin": "github", "actorKind": "user",
      "status": "success", "code": null, "cluster": "node-3",
      "ref": "main", "commit": "a1b2c3d", "bytes": 4210334, "files": 812,
      "steps": [{ "name": "received", "at": "2026-09-02T12:00:01.000Z" }],
      "startedAt": "2026-09-02T12:00:00.000Z",
      "finishedAt": "2026-09-02T12:01:12.000Z",
      "durationMs": 72000, "live": false
    }]
  }
}

Sobe o container.

Para o container. A cota continua reservada.

Reinicia o container.

Troca o limite de memória e recria o container.

O caminho da API usa /memory — o verbo já está no método. A rota equivalente do painel tem outro nome por razões históricas.

As quatro recusas de memória têm códigos distintos de propósito: “abaixo do mínimo do tipo”, “acima do teto por container”, “acima do que sobra do plano” e “valor inválido” pedem ações diferentes de quem integrou.

Refaz o deploy do que já está vinculado, sem esperar um commit.

Os domínios da aplicação e o estado de cada um.

state é a chave que diz onde o domínio parou; reason é o código do motivo, e detail — quando existe — é o texto cru do provedor de DNS, para ser mostrado sem tradução. ownership traz o registro TXT quando ele ainda é necessário.

{
  "status": "success",
  "response": [{
    "id": "dom_01H…", "hostname": "loja.exemplo.com", "apex": false,
    "state": "pending", "reason": "AWAITING_DNS", "detail": null, "actionable": true,
    "ownership": { "type": "TXT", "name": "_cf-custom-hostname.loja", "value": "…" },
    "createdAt": "2026-09-01T10:00:00.000Z", "verifiedAt": null
  }]
}

Adiciona um domínio próprio ao website.

Só vale para website — uma aplicação sem porta exposta não tem o que servir num domínio.

Reconsulta o estado do domínio agora.

Use depois de acertar o DNS, em vez de esperar a verificação periódica.

Remove o domínio da aplicação.

Todas as snapshots da conta, agrupadas por aplicação.

A paginação é por aplicação — um grupo é um cartão na tela —, e não por versão. Busca e ordenação rodam no servidor.

As snapshots de uma aplicação.

Gera uma snapshot agora.

Limite: Duas por dia para cada 256 MB de RAM do plano, e um intervalo mínimo de 60 segundos entre duas criações da mesma aplicação.

O andamento do restore em curso, se houver um.

Responde 200 com response: null quando não há restore nenhum — é um estado válido, e não um erro.

Restaura a aplicação a partir de uma snapshot.

Uma URL assinada para baixar a snapshot.

A URL é gerada na hora e vale por poucos minutos — tempo de baixar, não de guardar num script. Peça uma nova quando precisar de novo.

Apaga uma snapshot.

Fica fora de /apps/:app_id/ porque a snapshot é um recurso da conta: apagar a aplicação já leva as dela junto, e esta rota trata do que sobrou.

O catálogo de engines e versões disponíveis.

Chame antes de criar: é a lista que diz quais versões existem e qual é a recomendada de cada engine.

{
  "status": "success",
  "response": [{
    "key": "postgres", "label": "PostgreSQL",
    "versions": ["17", "16", "15"], "recommended": "17",
    "port": 5432, "urlScheme": "postgresql",
    "envKey": "DATABASE_URL", "hasDatabaseName": true
  }]
}

Os bancos da conta, com o estado ao vivo de cada um.

Provisiona um banco.

Responde 201 assim que o banco é criado e o endereço está reservado; o provisionamento termina em segundo plano. Acompanhe por /deploys do banco — só conecte quando ele estiver running.

Um banco, com host, porta, volume e estado.

Sem a senha e sem o certificado: os dois têm rota própria, para um segredo não viajar em toda listagem.

{
  "status": "success",
  "response": {
    "id": "db_01H…", "name": "loja", "engine": "postgres", "version": "17",
    "status": "running", "running": true, "health": "healthy",
    "host": "db-01h….nexcloud.gg", "port": 25431,
    "database": "loja", "user": "loja_app",
    "cpu": 1, "ram": 1024, "storage": 2048, "cluster": "node-3",
    "volume": "db_01h…", "volumePath": "/var/lib/postgresql/data",
    "volumeRetentionDays": 7, "autoBackup": true, "tls": true,
    "slowQueries": true, "lastBackupAt": "2026-09-01T03:00:00.000Z",
    "createdAt": "2026-06-11T18:22:04.000Z"
  }
}

Apaga o banco. O volume vai para quarentena.

Start, stop ou restart do engine.

O log do container do banco.

A série de consumo do banco.

Quem está conectado agora, e o teto configurado.

Troca o teto de conexões do engine.

Recria o container: max_connections é opção de start, e um restart reusaria os mesmos argumentos. O volume é preservado.

Limite: 5 por minuto.

O certificado da CA da plataforma.

É o mesmo para todos os bancos — é a CA da plataforma, não a do banco —, e é ele que permite verificar o servidor de verdade em vez de aceitar qualquer certificado.

O provisionamento do banco, passo a passo.

Usuário, senha em claro e a connection string.

{
  "status": "success",
  "response": {
    "host": "db-01h….nexcloud.gg", "port": 25431,
    "user": "loja_app", "password": "…", "database": "loja",
    "uri": "postgresql://loja_app:…@db-01h….nexcloud.gg:25431/loja?sslmode=verify-full"
  }
}

Limite: 30 por minuto — cada chamada é um segredo saindo.

As variáveis de ambiente do banco, em dois grupos.

O que está dentro do container, e o que a plataforma monta para a sua aplicação ler.

Limite: 30 por minuto.

Gera uma senha nova para o banco.

As aplicações vinculadas têm a variável reescrita e são reiniciadas. Quem conecta com a senha antiga de fora perde acesso na hora — é o ponto.

Limite: 5 por minuto.

As tabelas do banco — ou as chaves, no Redis e no Valkey.

As linhas de uma tabela, paginadas, com o esquema e a chave primária.

Insere uma linha.

Limite: 60 por minuto.

Altera uma linha.

O WHERE é montado com a chave primária inteira, lida do banco no momento da escrita — é o que garante, pelo próprio engine, que no máximo uma linha é atingida.

Limite: 60 por minuto.

Apaga uma linha.

Limite: 60 por minuto.

Roda um comando no banco.

O comando não é validado nem reescrito — é o mesmo poder que a connection string já dá a quem tem o banco. O que limita é a posse, o teto de tempo do engine e o teto de saída.

Limite: 120 por minuto.

Os backups do banco, do mais recente.

{
  "status": "success",
  "response": [{
    "id": "bkp_01H…", "size": 4823110, "engine": "postgres",
    "state": "ready", "error": null, "origin": "auto",
    "createdAt": "2026-09-01T03:00:00.000Z",
    "expiresAt": "2026-09-08T03:00:00.000Z"
  }]
}

Gera um backup agora.

Síncrona de propósito: um dump termina em segundos na maioria dos bancos, e devolver o resultado direto poupa um segundo estado para acompanhar.

Limite: 6 por minuto.

Liga ou desliga o backup automático.

Uma URL assinada para baixar o dump.

Apaga um backup.

Restaura o banco a partir de um backup.

Sobrescreve e tem indisponibilidade. Os comandos de restauração derrubam e recriam os objetos — aplicar um dump por cima de dados existentes daria conflito de chave em qualquer engine.

Limite: 3 por minuto.

As aplicações vinculadas a este banco.

Vincula uma aplicação, escrevendo a variável no .env dela.

A aplicação é reiniciada só se o arquivo mudou — vincular duas vezes o mesmo banco não derruba nada.

{
  "status": "success",
  "response": { "appId": "app_01H…", "appName": "api-loja", "envKey": "DATABASE_URL", "restarted": true }
}

Desvincula a aplicação e remove a variável.

Os arquivos da conta, paginados, com o uso da cota.

O uso volta em toda resposta: buscá-lo numa segunda chamada faria a barra de cota piscar desencontrada da lista.

{
  "status": "success",
  "response": {
    "page": 1, "limit": 24, "perpage": 24, "total": 42, "pages": 2,
    "usage": { "limit": 5368709120, "used": 220200960, "available": 5148508160, "files": 42 },
    "objects": [{
      "id": "b1f0…", "filename": "logo.png", "contentType": "image/png",
      "size": 20481, "createdAt": "2026-08-20T12:00:00.000Z",
      "url": "https://cdn.nexcloud.gg/blob/b1f0….png"
    }]
  }
}

Confere o arquivo no armazenamento, e não o registro dele.

É a chamada que diz se o arquivo realmente está lá, qual é o tamanho real e qual é o tipo de verdade — o .png que é um JPEG por dentro aparece aqui. Por ser mais cara que a listagem, tem teto próprio.

Limite: 60 por minuto.

Envia um arquivo e o publica no CDN.

multipart/form-data com um arquivo. A resposta traz o objeto — com a URL pública — e o uso da cota já atualizado.

Executáveis e arquivos interpretáveis por servidor são recusados por extensão e pelos primeiros bytes — renomear não contorna.

BLOB_NOT_IN_PLAN e BLOB_QUOTA_EXCEEDED são recusas diferentes: a primeira é “seu plano não inclui blob”, e apagar arquivo não resolve.

Apaga um arquivo do CDN e libera a cota.

Apaga todo o blob storage da conta.

Não há confirmação no protocolo — o método e o caminho já dizem o que a chamada faz. Quem confirma é a interface que a chamar.