Templates

Prompts reutilizaveis com variaveis — defina uma vez, use em qualquer chamada.

Copiar como .md

Templates sao prompts reutilizaveis com variaveis. Crie uma vez e use em qualquer chamada de /process ou /chat.

Sintaxe de variaveis

Use {{nomeVariavel}} no promptTemplate:

Escreva um email profissional para {{empresa}} sobre {{assunto}}. Tom: {{tom}}.

Listar templates

curl https://api.buildship.com.br/api/v1/templates \
  -H "X-API-Key: bld_sua_chave"

Criar template

curl -X POST https://api.buildship.com.br/api/v1/templates \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gerador de email",
    "promptTemplate": "Escreva um email para {{empresa}} sobre {{assunto}}. Tom: {{tom}}.",
    "variables": {
      "empresa": "Nome da empresa destinataria",
      "assunto": "Assunto do email",
      "tom": "formal"
    },
    "description": "Gera emails profissionais",
    "tags": ["email", "comercial"]
  }'

Resposta:

{
  "id": "tmpl_abc123",
  "name": "Gerador de email",
  "slug": "gerador-de-email",
  "promptTemplate": "...",
  "variables": { "empresa": "...", "assunto": "...", "tom": "formal" },
  "usageCount": 0,
  "createdAt": "2026-04-28T10:00:00Z"
}

Atualizar template

curl -X PUT https://api.buildship.com.br/api/v1/templates/tmpl_abc123 \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "promptTemplate": "Escreva um email curto para {{empresa}}...",
    "variables": { "empresa": "..." }
  }'

Deletar template

curl -X DELETE https://api.buildship.com.br/api/v1/templates/tmpl_abc123 \
  -H "X-API-Key: bld_sua_chave"

Usar template numa chamada

Em vez de passar prompt, passa templateId + templateVars:

curl -X POST https://api.buildship.com.br/api/v1/chat \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_abc123",
    "templateVars": {
      "empresa": "Acme Corp",
      "assunto": "Proposta comercial",
      "tom": "formal"
    },
    "endUserId": "user-456"
  }'

A IA recebe o promptTemplate com as variaveis substituidas.

Defaults nas variaveis

No campo variables do template, o valor funciona como descricao OU default:

{
  "variables": {
    "tom": "formal",        // default = "formal" se nao passar
    "empresa": "Empresa X"  // descricao da variavel
  }
}

Boas praticas

• Nomes descritivos: gerador-email-comercial em vez de tmpl1
• Variaveis claras: {{empresa_destino}} em vez de {{e}}
• Versione: tags como v1, v2 em tags pra trackear evolucao
• Teste antes de publicar: rode /chat com templateId + templateVars mockados e veja a saida

Exemplo: Pipeline de extracao de CV

{
  "name": "Extrator de CV",
  "promptTemplate": "Extraia do curriculo anexo:\n- Nome\n- Email\n- Telefone\n- Anos de experiencia em {{area}}\n- Formacao\n\nRetorne em JSON com chaves: name, email, phone, experience_years, education.",
  "variables": {
    "area": "engenharia de software"
  }
}

Use:

curl -X POST .../api/v1/process \
  -F "file=@cv.pdf" \
  -F "templateId=tmpl_extrator" \
  -F "templateVars={\"area\": \"data science\"}"