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	sim
items[].id	string	sim
items[].name	string	sim
items[].version	integer	sim
items[].params	array	sim
items[].params[].name	string	sim
items[].params[].type	string	sim
items[].params[].default	any	não	Valor padrão (qualquer 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 e a tabela de erros): 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	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.

{
  "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	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.

{
  "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	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.

{
  "error": "quota_exceeded",
  "message": "Limite de serviços do plano atingido."
}

Erros comuns

Corpo {"error", "message", "details"?} (veja Autenticação e visão geral e a tabela de erros): 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.