Criar um template privado

curl -X POST https://api.vertracloud.app/v1/templates \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -F 'manifest=<manifest.json' \
  -F 'sources[bot][email protected]'

{
  "response": {
    "id": "tpl-abc123def456",
    "slug": "support-bot",
    "origin": "private",
    "visibility": "public",
    "name": { "pt-br": "Bot de suporte", "en": "Support bot" },
    "description": { "pt-br": "Bot que responde o suporte.", "en": "A bot that answers support." },
    "category": "bots",
    "tags": ["discord", "support"],
    "icon_url": null,
    "author_display": "Ana",
    "links": {},
    "landing": null,
    "featured": false,
    "current_version": {
      "id": "tplv-111222333444",
      "version": "1.0.0",
      "security": false,
      "created_at": "2026-10-27T14:02:00Z"
    },
    "services": [
      {
        "id": "bot",
        "kind": "app",
        "source_type": "code",
        "database": null,
        "blob_visibility": null,
        "ram": { "min": 256, "recommended": 512 },
        "web": "none",
        "conditional": false
      }
    ],
    "creates_stack": false,
    "ram_min_total": 256,
    "byok": false,
    "required_plan": "economy",
    "code_view": true,
    "uses_count": null,
    "owner": { "user_id": "1234567890123456789", "workspace_id": null },
    "github": null,
    "inputs": [],
    "permissions": {
      "code_view": true,
      "code_edit": true,
      "ram_change": true,
      "ram_below_min": false,
      "ram_above_max": true,
      "env_add": true,
      "commands_edit": true,
      "terminal": false,
      "save_as_template": true,
      "detach": true
    },
    "outputs": [],
    "readme": null,
    "changelog": null,
    "created_at": "2026-10-27T14:02:00Z",
    "updated_at": "2026-10-27T14:02:00Z"
  }
}

POST

templates

curl -X POST https://api.vertracloud.app/v1/templates \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -F 'manifest=<manifest.json' \
  -F 'sources[bot][email protected]'

{
  "response": {
    "id": "tpl-abc123def456",
    "slug": "support-bot",
    "origin": "private",
    "visibility": "public",
    "name": { "pt-br": "Bot de suporte", "en": "Support bot" },
    "description": { "pt-br": "Bot que responde o suporte.", "en": "A bot that answers support." },
    "category": "bots",
    "tags": ["discord", "support"],
    "icon_url": null,
    "author_display": "Ana",
    "links": {},
    "landing": null,
    "featured": false,
    "current_version": {
      "id": "tplv-111222333444",
      "version": "1.0.0",
      "security": false,
      "created_at": "2026-10-27T14:02:00Z"
    },
    "services": [
      {
        "id": "bot",
        "kind": "app",
        "source_type": "code",
        "database": null,
        "blob_visibility": null,
        "ram": { "min": 256, "recommended": 512 },
        "web": "none",
        "conditional": false
      }
    ],
    "creates_stack": false,
    "ram_min_total": 256,
    "byok": false,
    "required_plan": "economy",
    "code_view": true,
    "uses_count": null,
    "owner": { "user_id": "1234567890123456789", "workspace_id": null },
    "github": null,
    "inputs": [],
    "permissions": {
      "code_view": true,
      "code_edit": true,
      "ram_change": true,
      "ram_below_min": false,
      "ram_above_max": true,
      "env_add": true,
      "commands_edit": true,
      "terminal": false,
      "save_as_template": true,
      "detach": true
    },
    "outputs": [],
    "readme": null,
    "changelog": null,
    "created_at": "2026-10-27T14:02:00Z",
    "updated_at": "2026-10-27T14:02:00Z"
  }
}

Esta chamada cria um template privado com a primeira versão e responde 201 com o template. A requisição é multipart/form-data: o manifesto vai em um campo de texto, e cada serviço que executa o seu código vai em uma parte ZIP. Para começar a partir de um app ou de uma stack que você já tem, use Criar template a partir de app ou Criar template a partir de stack. Precisa do escopo templates:write quando chamado com uma chave de API. Só planos que podem criar imagens Docker personalizadas podem criar templates, e cada conta tem no máximo 5 templates privados, pessoais e de workspace somados. Em um workspace, só o dono do workspace cria templates. Um template privado não é revisado pela Vertra Cloud: quem o recebe vê o aviso “Não verificado pela Vertra”. Confira o manifesto antes com Validar manifesto. O formato está na referência do manifesto. O ZIP de um serviço é verificado antes de ser armazenado. O envio inteiro é recusado com TEMPLATE_SECRET_IN_SOURCE quando tem um arquivo .env que não é um exemplo, uma chave privada ou um token conhecido; details.files lista apenas os caminhos. Pastas .vertra/ são descartadas, e arquivos .env* nunca entram em um template.

string

obrigatório

O manifesto como string JSON serializada, seguindo o schema do manifesto. Um serviço cujo source.type é image se refere a uma imagem da sua conta pelo ID em source.image.

file

Uma parte ZIP por serviço do manifesto cuja origem é code, nomeada pelo id do serviço, por exemplo sources[bot]. Obrigatória para cada um desses serviços.

string

A mensagem da primeira versão, como objeto JSON serializado com pt-br (obrigatório), en e es.

string

O workspace que será dono do template. Sem ele, o template é seu.

curl -X POST https://api.vertracloud.app/v1/templates \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -F 'manifest=<manifest.json' \
  -F 'sources[bot][email protected]'

Resposta

object

O template, com a primeira versão.

Mostrar Mostrar objeto

string

O ID do template.

string

O slug do template, tirado do id do manifesto.

string

private para os templates que você cria. Os templates do catálogo são vertra ou community.

string

public, beta, hidden ou deprecated.

object

O nome por idioma: pt-br, en e es. Um en ou es ausente cai para pt-br.

object

A descrição por idioma, no mesmo formato de name.

string

automation, ai-agents, bots, apis, cms, monitoring, starters, databases ou other.

string[]

As tags.

string | null

URL do ícone, ou null quando o template não tem um.

string | null

O nome exibido como autor. null para os templates feitos pela plataforma.

object

Links do software que o template empacota: website, docs, source e license, todos opcionais.

string | null

Slug de uma página pública dedicada, ou null.

boolean

Destacado na galeria.

object

A versão mais recente: id, version (versão semântica), security (true para uma versão de segurança) e created_at.

object[]

O que o template cria. Cada serviço tem id, kind (app, database ou blob), source_type (code, image ou null), database (o engine, ou null), blob_visibility, ram (min, recommended e max opcional, em MB), web (required, optional, none ou null) e conditional (true quando o serviço só é criado para algumas respostas).

boolean

true quando usar o template cria uma stack (dois ou mais serviços).

integer

A soma da memória mínima de todos os serviços, em MB.

boolean

true quando quem usa o template traz a própria chave para um modelo de IA.

string

O plano mais baixo que pode usar o template.

boolean

false para um template fechado: quem o usa não pode ver o código dele.

integer | null

Sempre null para um template privado.

object | null

user_id e workspace_id (null quando o template pertence ao usuário).

object | null

O repositório vinculado (repository no formato owner/name, e branch), ou null quando o template não está vinculado.

object[]

As perguntas que o usuário responde ao usar o template. Veja Placeholders e inputs.

object

As permissões efetivas dos apps criados a partir do template, depois dos padrões e das restrições de um template fechado: code_view, code_edit, ram_change, ram_below_min, ram_above_max, env_add, commands_edit, terminal, save_as_template e detach, todos booleanos.

object[]

O que o assistente mostra no fim de um deploy: label, value e as flags opcionais secret e once.

object | null

A documentação do template (Markdown) por idioma, ou null.

object | null

O changelog da versão mais recente por idioma, ou null.

object

O que usar o template faria na sua conta (fits, reasons, required_ram, free_ram, needs_image_slot, image_slots_free, in_use e in_use_count). Presente apenas nas chamadas autenticadas que leem o template.

string

Quando o template foi criado.

string

Quando o template foi atualizado pela última vez.

{
  "response": {
    "id": "tpl-abc123def456",
    "slug": "support-bot",
    "origin": "private",
    "visibility": "public",
    "name": { "pt-br": "Bot de suporte", "en": "Support bot" },
    "description": { "pt-br": "Bot que responde o suporte.", "en": "A bot that answers support." },
    "category": "bots",
    "tags": ["discord", "support"],
    "icon_url": null,
    "author_display": "Ana",
    "links": {},
    "landing": null,
    "featured": false,
    "current_version": {
      "id": "tplv-111222333444",
      "version": "1.0.0",
      "security": false,
      "created_at": "2026-10-27T14:02:00Z"
    },
    "services": [
      {
        "id": "bot",
        "kind": "app",
        "source_type": "code",
        "database": null,
        "blob_visibility": null,
        "ram": { "min": 256, "recommended": 512 },
        "web": "none",
        "conditional": false
      }
    ],
    "creates_stack": false,
    "ram_min_total": 256,
    "byok": false,
    "required_plan": "economy",
    "code_view": true,
    "uses_count": null,
    "owner": { "user_id": "1234567890123456789", "workspace_id": null },
    "github": null,
    "inputs": [],
    "permissions": {
      "code_view": true,
      "code_edit": true,
      "ram_change": true,
      "ram_below_min": false,
      "ram_above_max": true,
      "env_add": true,
      "commands_edit": true,
      "terminal": false,
      "save_as_template": true,
      "detach": true
    },
    "outputs": [],
    "readme": null,
    "changelog": null,
    "created_at": "2026-10-27T14:02:00Z",
    "updated_at": "2026-10-27T14:02:00Z"
  }
}

Respostas de erro

string

O código de erro que indica o motivo da falha. Valores possíveis:

API_KEY_SCOPE_DENIED: A chave de API não tem o escopo templates:write (403).
TEMPLATE_MANIFEST_INVALID: O manifesto não é válido; details.issues lista cada achado com o path e o code. Nada é criado.
TEMPLATE_SOURCE_REQUIRED: Um serviço code não tem uma parte ZIP.
TEMPLATE_SECRET_IN_SOURCE: Um ZIP tem um segredo (um arquivo .env, uma chave privada ou um token); details.files lista os caminhos (400).
TEMPLATE_SLUG_TAKEN: O id do manifesto já está em uso entre os seus templates ou é uma palavra reservada.
TEMPLATE_PRIVATE_LIMIT_REACHED: A conta já tem 5 templates privados.
PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES: O plano não pode criar imagens Docker personalizadas, então não pode criar templates.
IMAGE_NOT_FOUND: Um serviço image se refere a uma imagem que não é sua ou não tem um build bem-sucedido.
WORKSPACE_OWNER_ONLY: workspace_id foi enviado e quem chama não é o dono desse workspace.

{
  "code": "TEMPLATE_MANIFEST_INVALID",
  "details": {
    "issues": [{ "path": "services.bot.ram.min", "code": "invalid_ram", "message": "ram.min must be a positive number of MB" }]
  }
}

Última modificação em 28 de outubro de 2026

Visão geral

Endpoints

Criar um template privado

Resposta

Respostas de erro

​Resposta

​Respostas de erro

Resposta

Respostas de erro