Pular para o conteúdo principal
POST
Criar aplicação
A aplicação tem duas fontes mutuamente exclusivas — envie exatamente uma entre file e snapshot_id. Nenhuma → SOURCE_REQUIRED; as duas → SOURCE_CONFLICT.
file
O arquivo ZIP com o código da aplicação (tamanho máximo: 100 MB). Ausente quando a fonte é snapshot_id.
string
Fonte alternativa a file: o ID de um snapshot de aplicação a partir do qual criar a aplicação. A plataforma baixa o snapshot (que já traz o vertracloud.config) e constrói a aplicação a partir dele. Enviado como campo de texto do corpo multipart — mesmo limite de tamanho de file (100 MB).
string
A quantidade de RAM a alocar para a aplicação, em MB. Mínimo de 100 MB. Obrigatório com file; com snapshot_id é opcional e usa como padrão o vertracloud.config do snapshot. Quando um subdomain é solicitado, o valor é elevado automaticamente para pelo menos 512 MB — aplicações web têm o seu próprio piso de memória.
string
O comando de inicialização da aplicação.
string
Um comando de build opcional, de até 512 caracteres (por exemplo npm run build). É executado após a instalação das dependências e antes de a aplicação iniciar, em um ambiente de build isolado — 2× a RAM da aplicação (mínimo de 1.024 MB, máximo de 4.096 MB), com timeout de 10 minutos. As devDependencies são instaladas quando um comando de build está definido. Disponível em todos os planos. Veja Atualizar configuração da aplicação para alterá-lo depois.
string
O arquivo principal da aplicação. Obrigatório com file; com snapshot_id é opcional e usa como padrão o vertracloud.config do snapshot.
string
Opcional. Força a linguagem de runtime em vez de detectá-la a partir do projeto: uma de javascript, typescript, bun, python, static, php, go, ruby, java, rust, deno, dotnet, elixir. Precedência: este campo, depois LANGUAGE= no vertracloud.config, depois a detecção. Qualquer outro valor é recusado com INVALID_LANGUAGE.
string
Obrigatório com file; com snapshot_id usa como padrão o vertracloud.config do snapshot. A versão do runtime da aplicação: recommended, latest ou uma versão específica suportada pelo runtime detectado (por exemplo 22).
string
obrigatório
O nome de exibição da aplicação. Máximo de 50 caracteres.
string
Uma descrição da aplicação.
string
O ID do workspace a associar à aplicação, se aplicável.
string
O subdomínio da aplicação (por exemplo myapp). Espaços são trocados por - e o valor é convertido para minúsculas antes da validação; o formato aceito é ^[a-z0-9-]+$. Envie random para que a plataforma escolha um para você. Omita o campo para criar uma aplicação privada, sem publicação na web — você pode ativá-la depois com Publicar aplicação na web.Requer suporte do plano à publicação na web.
string
Uma string JSON com um array de variáveis de ambiente, cada uma com key, value e um note opcional. Tamanho máximo da chave: 255. Tamanho máximo do valor: 3072. Tamanho máximo da nota: 50.

Resposta

A criação é assíncrona: a resposta é 202 Accepted com a aplicação em status: "building". Acompanhe com Detalhes da aplicação ou com os logs em tempo real até que status seja up ou down. Enquanto estiver building, iniciar, parar, reiniciar, deploys de arquivos, rollback, snapshots, restaurações e alterações de configuração respondem 409 APP_BUILDING; excluir a aplicação é permitido. Se o build for interrompido, a aplicação permanece down e BUILD_INTERRUPTED aparece no log dela; se a plataforma cancelar a criação (por exemplo, porque a fila está cheia), a aplicação deixa de existir e os Detalhes da aplicação respondem 404.
object
Os detalhes da aplicação criada.

Respostas de erro

string
O código de erro que indica o motivo da falha. Valores possíveis:
  • VALIDATION_ERROR: o corpo multipart falhou na validação (400). A resposta também traz message e path apontando para o campo com problema.
  • USER_NOT_FOUND: não foi possível identificar o usuário autenticado (401).
  • MAX_APPS_REACHED: foi atingido o limite de aplicações do plano (403).
  • INVALID_ZIP: o arquivo enviado não é um ZIP legível (truncado ou corrompido) (400).
  • MAIN_FILE_NOT_FOUND: o arquivo indicado em main não existe dentro do ZIP (400).
  • ZIP_TOO_SMALL: o arquivo enviado tem menos de 100 bytes (400).
  • FILE_TOO_LARGE: o arquivo enviado ultrapassa o limite de 100 MB (400).
  • SOURCE_REQUIRED: nem file nem snapshot_id foram enviados (400).
  • SOURCE_CONFLICT: file e snapshot_id foram enviados juntos (400).
  • SNAPSHOT_NOT_FOUND: o snapshot_id não existe ou não pertence a quem fez a chamada (404).
  • SNAPSHOT_TYPE_MISMATCH: o snapshot é de banco de dados, não de aplicação (400).
  • SNAPSHOT_TOO_LARGE: o snapshot ultrapassa o mesmo limite de criação de 100 MB de file (400).
  • MEMORY_REQUIRED: memory foi omitido e o vertracloud.config do snapshot não tem um MEMORY utilizável (400).
  • PLAN_REQUIRED: o dono não tem um plano ativo, então uma nova aplicação não pode ser criada, ou um subdomain foi solicitado sem um (403).
  • PLAN_DOES_NOT_SUPPORT_WEB_PUBLISH: um subdomain foi solicitado, mas o plano do dono não inclui publicação na web (403).
  • INVALID_MEMORY_FORMAT: memory não é um número (400).
  • MEMORY_MUST_BE_INTEGER: memory não é um inteiro (400).
  • MEMORY_BELOW_MINIMUM: memory está abaixo do mínimo para o tipo da aplicação (400).
  • MEMORY_LIMIT_EXCEEDED: a memória solicitada excede a memória ainda disponível no plano (400).
  • SUBDOMAIN_TAKEN: outra aplicação já usa esse subdomínio (409).
  • SUBDOMAIN_FORBIDDEN: o subdomínio solicitado está na lista de nomes reservados da plataforma (400).
  • USER_LIMITS_NOT_FOUND: o registro de limites do dono não pôde ser carregado (404).
  • INVALID_LANGUAGE: a linguagem não é suportada ou não pôde ser determinada (400).
  • DEPLOY_RATE_LIMITED: foi atingido o orçamento horário de deploys da conta para o seu plano (429). Veja Introdução à referência da API.
  • INTERNAL_SERVER_ERROR: falha inesperada, incluindo uma aplicação que foi criada mas não pôde ser lida de volta (500).
string
Uma mensagem descritiva com detalhes adicionais sobre o erro. Presente em VALIDATION_ERROR.
Uma aplicação criada sem subdomain continua privada. Você pode ativar a publicação na web depois com Publicar aplicação na web, e desativá-la de novo na mesma rota.
Última modificação em 28 de outubro de 2026