Templates API

A API de Templates permite consultar o catálogo da organização ativa, criar e revisar pontos de partida para aplicações HTTP e iniciar um projeto com uma revisão específica. As rotas exigem autenticação de usuário ou API key da organização e o contexto x-organization-id.

Autenticação e contexto

Envie um token de usuário no header Authorization: Bearer <token> ou uma API key de organização conforme o fluxo de autenticação usado pela sua integração. Inclua x-organization-id em todas as chamadas. A organização ativa define os templates privados e o destino de um novo projeto.

Authorization: Bearer <token>
x-organization-id: <organization-id>
Content-Type: application/json

O catálogo público continua exigindo uma sessão autenticada. A permissão de leitura pública não concede permissão para criar projetos ou alterar templates.

Listar templates

GET /v1/templates?scope=organization&sort=updated&page=1&limit=20

Parâmetro	Obrigatório	Valores
`scope`	Sim	`organization` ou `public`
`sort`	Sim	`updated`, `newest` ou `most_used`
`official`	Não	`true` ou `false`; disponível com `scope=public`
`page`	Não	Página iniciando em 1
`limit`	Não	Até 50 itens

organization retorna templates acessíveis na organização ativa, ordenados pela última atualização. public retorna templates publicados. most_used usa organizações consumidoras únicas como critério principal e deploys concluídos como desempate. Use official=true para retornar somente Templates publicados pela Zenifra ou por parceiros oficiais.

Cada Template retornado possui official, um booleano que informa se a organização autora é uma publicadora oficial. Esse campo é informativo e não altera permissões ou implantação.

Obter, criar e editar

GET /v1/templates/:id
POST /v1/templates
PATCH /v1/templates/:id

O corpo de criação e edição contém name, summary, description, tags, application, variables e defaults. A aplicação informa reference, port e storage_path; os padrões informam plano, cobrança, exposição, instâncias, auto-scaling e storage.

Referências públicas são aceitas para Docker Hub, GHCR, Quay e GitLab Registry. A Zenifra valida a aplicação antes de aceitar a revisão. Não envie credenciais, tokens ou valores secretos no template.

Cada edição exige expected_revision e uma revisão antiga retorna 409 Conflict. Variáveis secretas não podem ter default_value.

Publicar e remover

PATCH /v1/templates/:id/visibility
DELETE /v1/templates/:id

O corpo de visibilidade é { "visibility": "public", "expected_revision": 2 }. A criação começa privada. Publicar ou tornar privado exige template.publish; remoção exige template.delete e expected_revision. A remoção é lógica e não altera projetos já criados.

Criar projeto por template

Use o payload alternativo de POST /v1/project:

{
  "template_id": "507f1f77bcf86cd799439011",
  "template_revision": 2,
  "name": "atendimento-api",
  "description": "Projeto criado a partir de um template",
  "plan": "basic",
  "payment_mode": "monthly",
  "config": {
    "exposure": "public",
    "instances": 1,
    "storage": { "persistent": true, "capacity": 10 },
    "envs": [
      { "name": "APP_ENV", "value": "production" },
      { "name": "APP_SECRET", "value": "valor-informado-no-deploy" }
    ],
    "network_access": {
      "ingress_white_list": [{ "cidr": "0.0.0.0/0", "description": "Acesso ao projeto" }],
      "ingress_black_list": []
    }
  }
}

A aplicação, porta, tipo HTTP e pasta persistente vêm da revisão do template. O request deve conter exatamente as variáveis declaradas. A implantação exige project.create e, para template privado, template.read. Falhas não contam uso nem alteram o ranking.

Limites

Leituras têm limite de 100 requisições por minuto. Criação e edição têm limite de 10 por minuto. Publicação e remoção têm limite de 5 por minuto. Respeite respostas 429 e aguarde antes de tentar novamente.