claude-plugins/infraestrutura/skills/easypanel-api/SKILL.md

name, description, author, version, quality_score, user_invocable, desk_task

name	description	author	version	quality_score	user_invocable	desk_task
easypanel-api	EasyPanel official tRPC API reference. All endpoints for projects, services, deploy, settings. Use when user mentions "easypanel api", "criar serviço easypanel", "deploy easypanel", "easypanel config".	Descomplicar® Crescimento Digital	1.0.0	70	true	1502

/easypanel-api - API Oficial EasyPanel

Referência completa da API tRPC do EasyPanel. Baseado em engenharia reversa do SDK oficial.

---

Autenticação

# Token guardado em /etc/easypanel/.api-token (chmod 600)
TOKEN=$(cat /etc/easypanel/.api-token)

# Header obrigatório
-H "Authorization: Bearer $TOKEN"

---

Base URL

http://localhost:3000/api/trpc/

Nota: Usar localhost via SSH, não expor externamente.

---

Formato de Requests

GET (leitura)

curl -s "http://localhost:3000/api/trpc/ENDPOINT?input=URL_ENCODED_JSON" \
  -H "Authorization: Bearer $TOKEN"

POST (escrita)

curl -s -X POST "http://localhost:3000/api/trpc/ENDPOINT" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{...}}'

---

Projects API

Listar Projectos

curl -s "http://localhost:3000/api/trpc/projects.listProjects" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "result": {
    "data": {
      "json": [
        {"name": "descomplicar", "createdAt": "2024-12-30T01:32:45.738Z"},
        {"name": "clientes", "createdAt": "2024-12-30T16:18:38.840Z"}
      ]
    }
  }
}

Listar Projectos com Serviços

curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \
  -H "Authorization: Bearer $TOKEN"

Response: Lista completa de projectos e todos os serviços com configurações.

Criar Projecto

curl -s -X POST "http://localhost:3000/api/trpc/projects.createProject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"name":"novo-projecto"}}'

Destruir Projecto

curl -s -X POST "http://localhost:3000/api/trpc/projects.destroyProject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"nome-projecto"}}'

Inspeccionar Projecto

curl -s "http://localhost:3000/api/trpc/projects.inspectProject?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%7D%7D" \
  -H "Authorization: Bearer $TOKEN"

---

Services API

Service Types

Type	Descrição
app	Aplicação (Node.js, Python, Go, etc.)
mysql	MySQL database
mariadb	MariaDB database
postgres	PostgreSQL database
mongo	MongoDB database
redis	Redis cache

Criar Serviço App

curl -s -X POST "http://localhost:3000/api/trpc/services.app.createService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'

Criar Serviço Database

# PostgreSQL
curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.createService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-db"}}'

# MySQL
curl -s -X POST "http://localhost:3000/api/trpc/services.mysql.createService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"mysql-db"}}'

# Redis
curl -s -X POST "http://localhost:3000/api/trpc/services.redis.createService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"cache"}}'

Inspeccionar Serviço

# URL encode: {"json":{"projectName":"descomplicar","serviceName":"dashboard_descomplicar"}}
curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22dashboard_descomplicar%22%7D%7D" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "projectName": "descomplicar",
  "name": "dashboard_descomplicar",
  "type": "app",
  "enabled": true,
  "token": "deploy-webhook-token",
  "source": {"type": "git", "repo": "https://...", "ref": "main"},
  "build": {"type": "nixpacks", "buildCommand": "npm run build"},
  "env": "VAR=value",
  "mounts": [],
  "ports": []
}

Deploy Serviço

curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'

Enable/Disable Serviço

# Disable
curl -s -X POST "http://localhost:3000/api/trpc/services.app.disableService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'

# Enable
curl -s -X POST "http://localhost:3000/api/trpc/services.app.enableService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'

Destruir Serviço

curl -s -X POST "http://localhost:3000/api/trpc/services.app.destroyService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'

---

Service Configuration API

Actualizar Source (GitHub)

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGithub" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "owner":"ealmeida",
    "repo":"MeuRepo",
    "ref":"main",
    "path":"/"
  }}'

Actualizar Source (Git Custom)

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "repo":"https://git.descomplicar.pt/org/repo",
    "ref":"main",
    "path":"/"
  }}'

Actualizar Source (Docker Image)

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceImage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "image":"node:22-alpine"
  }}'

Actualizar Environment Variables

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateEnv" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "env":"NODE_ENV=production\nPORT=3000\nDATABASE_URL=postgres://..."
  }}'

Actualizar Domains

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateDomains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "domains":[
      {"host":"api.descomplicar.pt","https":true,"port":3000}
    ]
  }}'

Actualizar Mounts

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateMounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "mounts":[
      {"type":"volume","name":"data","mountPath":"/app/data"}
    ]
  }}'

Actualizar Ports (non-HTTP)

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updatePorts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "ports":[
      {"published":8080,"target":3000,"protocol":"tcp"}
    ]
  }}'

Actualizar Resources

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateResources" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "resources":{
      "memoryLimit":"512m",
      "memoryReservation":"256m",
      "cpuLimit":1,
      "cpuReservation":0.5
    }
  }}'

Actualizar Build Config

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateBuild" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "build":{
      "type":"nixpacks",
      "buildCommand":"npm run build",
      "startCommand":"npm start"
    }
  }}'

Actualizar Deploy (Replicas, Command)

curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-api",
    "deploy":{
      "replicas":2,
      "command":"node dist/index.js",
      "zeroDowntime":true
    }
  }}'

---

Monitor API

System Stats

curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \
  -H "Authorization: Bearer $TOKEN"

Service Stats

curl -s "http://localhost:3000/api/trpc/monitor.getServiceStats?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22minha-api%22%7D%7D" \
  -H "Authorization: Bearer $TOKEN"

Docker Task Stats

curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \
  -H "Authorization: Bearer $TOKEN"

---

Logs API

Get Service Logs

curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22minha-api%22%2C%22tail%22%3A100%7D%7D" \
  -H "Authorization: Bearer $TOKEN"

---

Settings API

Get Server IP

curl -s "http://localhost:3000/api/trpc/settings.getServerIp" \
  -H "Authorization: Bearer $TOKEN"

Get Panel Domain

curl -s "http://localhost:3000/api/trpc/settings.getPanelDomain" \
  -H "Authorization: Bearer $TOKEN"

Set Panel Domain

curl -s -X POST "http://localhost:3000/api/trpc/settings.setPanelDomain" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"domain":"easy.descomplicar.pt"}}'

Get/Set Let's Encrypt Email

# Get
curl -s "http://localhost:3000/api/trpc/settings.getLetsEncryptEmail" \
  -H "Authorization: Bearer $TOKEN"

# Set
curl -s -X POST "http://localhost:3000/api/trpc/settings.setLetsEncryptEmail" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"email":"emanuel@descomplicar.pt"}}'

Restart Traefik

curl -s -X POST "http://localhost:3000/api/trpc/settings.restartTraefik" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{}}'

Restart EasyPanel

curl -s -X POST "http://localhost:3000/api/trpc/settings.restartEasypanel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{}}'

Prune Docker Images

curl -s -X POST "http://localhost:3000/api/trpc/settings.pruneDockerImages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{}}'

---

Database Backup API

Update Backup Config

curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.updateBackup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{
    "projectName":"descomplicar",
    "serviceName":"minha-db",
    "backup":{
      "enabled":true,
      "schedule":"0 3 * * *",
      "destination":{
        "type":"s3",
        "bucket":"backups",
        "region":"eu-west-1",
        "accessKey":"...",
        "secretKey":"..."
      }
    }
  }}'

---

Helper: URL Encode JSON

Para GET requests, o input deve ser URL encoded:

# Usando Python
INPUT='{"json":{"projectName":"descomplicar","serviceName":"api"}}'
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))")
curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" -H "Authorization: Bearer $TOKEN"

---

Wrapper Script

Criar /usr/local/bin/easypanel-api:

#!/bin/bash
# EasyPanel API wrapper
# Usage: easypanel-api <endpoint> [json-body]

TOKEN=$(cat /etc/easypanel/.api-token)
BASE="http://localhost:3000/api/trpc"

if [ -z "$2" ]; then
  # GET request
  curl -s "$BASE/$1" -H "Authorization: Bearer $TOKEN"
else
  # POST request
  curl -s -X POST "$BASE/$1" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "$2"
fi

Uso:

easypanel-api projects.listProjects
easypanel-api services.app.deployService '{"json":{"projectName":"descomplicar","serviceName":"api"}}'

---

Checklist Uso API

1. [ ] SSH para servidor easy
2. [ ] TOKEN=$(cat /etc/easypanel/.api-token)
3. [ ] Testar: curl -s "http://localhost:3000/api/trpc/projects.listProjects" -H "Authorization: Bearer $TOKEN"
4. [ ] Usar endpoints conforme documentado
5. [ ] Validar resposta (result.data.json)

---

Anti-Patterns

Anti-Pattern	Risco	Alternativa
Expor API externamente	Segurança	Usar apenas via SSH localhost
Hardcode token	Leak	Usar /etc/easypanel/.api-token
Não validar response	Erros silenciosos	Verificar result.data.json
POST sem Content-Type	Request falha	Sempre incluir header

---

Versão: 1.0.0 | Autor: Descomplicar® Fonte: Engenharia reversa SDK github.com/Easypanel-Community/easypanel