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

---
name: easypanel-api
description: 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".
author: Descomplicar® Crescimento Digital
version: 1.0.0
quality_score: 70
user_invocable: true
desk_task: 1502
---

# /easypanel-api - API Oficial EasyPanel

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

---

## Autenticação

```bash
# 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)
```bash
curl -s "http://localhost:3000/api/trpc/ENDPOINT?input=URL_ENCODED_JSON" \
  -H "Authorization: Bearer $TOKEN"
```

### POST (escrita)
```bash
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

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

**Response:**
```json
{
  "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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
# 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:**
```json
{
  "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

```bash
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

```bash
# 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

```bash
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)

```bash
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)

```bash
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)

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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)

```bash
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

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

### Service Stats

```bash
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

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

---

## Logs API

### Get Service Logs

```bash
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

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

### Get Panel Domain

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

### Set Panel Domain

```bash
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

```bash
# 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

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

### Restart EasyPanel

```bash
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

```bash
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

```bash
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:

```bash
# 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`:

```bash
#!/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:**
```bash
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