Pelican API

General

• Base URL: https://pelican.matias7235.com.ar/api/application/ (admin)
• Client API URL: https://pelican.matias7235.com.ar/api/client/ (acciones de servidor)
• Auth: Bearer token
• Content-Type: application/json

API Keys

Tipo	Prefijo	Dónde se crea	Permisos
Application	papp_...	Admin → API Keys	Administración (nodos, eggs, servidores, usuarios)
Client	pcli_...	Account → API Credentials	Control de servidores (start/stop, files, etc.)

Keys activas del homelab:

Key	Tipo
(ver nota "Pelican API" en Vaultwarden)	Application (full access)
pacc_88vux79Gr1D o pcli_... (no verificada aún)	Client

Endpoints disponibles

Nodes

Método	Ruta	Descripción
GET	/nodes	Listar nodos
GET	/nodes/{id}	Ver nodo
GET	/nodes/{id}/configuration	Obtener YAML de Wings
PATCH	/nodes/{id}	Actualizar specs
POST	/nodes/{id}/allocations	Crear allocation (IP:port)
GET	/nodes/{id}/allocations	Listar allocations

Servers

Método	Ruta	Descripción
GET	/servers	Listar servidores
POST	/servers	Crear servidor
GET	/servers/{id}	Ver servidor
PATCH	/servers/{id}/details	Cambiar nombre/owner
PATCH	/servers/{id}/build	Cambiar RAM/CPU/disk
PATCH	/servers/{id}/startup	Cambiar startup/variables
POST	/servers/{id}/suspend	Suspender
POST	/servers/{id}/unsuspend	Reactivar
POST	/servers/{id}/reinstall	Reinstalar
DELETE	/servers/{id}	Eliminar

Eggs

Método	Ruta	Descripción
GET	/eggs	Listar eggs
GET	/eggs/{id}	Ver egg
POST	/eggs/import	Importar egg (JSON en body)
DELETE	/eggs/{id}	Eliminar egg

Users

Método	Ruta	Descripción
GET	/users	Listar usuarios
POST	/users	Crear usuario
PATCH	/users/{id}	Actualizar usuario
DELETE	/users/{id}	Eliminar usuario

Ejemplos

Importar egg (Pterodactyl JSON)

curl -sL "$URL_DEL_EGG_JSON" \
  | curl -s -X POST "https://pelican.matias7235.com.ar/api/application/eggs/import" \
    -H "Authorization: Bearer papp_..." \
    -H "Content-Type: application/json" \
    -d @-

Importar egg (Pelican YAML — para forzar imagen default)

curl -s -X POST "https://pelican.matias7235.com.ar/api/application/eggs/import" \
  -H "Authorization: Bearer papp_..." \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import yaml, json
with open('egg.yaml') as f: d = yaml.safe_load(f)
print(json.dumps(d))
")"

Nota: El orden de docker_images importa — la primera imagen es la default. Poner Java 25 primero = default Java 25.

Crear allocation

curl -s -X POST "https://pelican.matias7235.com.ar/api/application/nodes/1/allocations" \
  -H "Authorization: Bearer papp_..." \
  -H "Content-Type: application/json" \
  -d '{"ip": "0.0.0.0", "ports": ["25565"]}'

Crear servidor (Paper MC con Java 25)

curl -s -X POST "https://pelican.matias7235.com.ar/api/application/servers" \
  -H "Authorization: Bearer papp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Minecraft Test",
    "user": 1,
    "egg": 3,
    "docker_image": "ghcr.io/pelican-eggs/yolks:java_25",
    "startup": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}}",
    "limits": {"memory": 4096, "swap": 0, "cpu": 100, "disk": 10000, "io": 500},
    "feature_limits": {"databases": 0, "allocations": 1, "backups": 0},
    "allocation": {"default": 1, "additional": []},
    "environment": {
      "MINECRAFT_VERSION": "latest",
      "SERVER_JARFILE": "server.jar",
      "BUILD_NUMBER": "latest"
    }
  }'

Ver nodo

curl -s "https://pelican.matias7235.com.ar/api/application/nodes/1" \
  -H "Authorization: Bearer papp_..."

Obtener config de Wings

curl -s "https://pelican.matias7235.com.ar/api/application/nodes/1/configuration" \
  -H "Authorization: Bearer papp_..."

Notas importantes

• Docker image: El endpoint PATCH /servers/{id}/details y PATCH /servers/{id}/startup NO cambian la imagen Docker efectiva. Para cambiar la imagen hay que recrear el server.
• Client API: Las papp_ NO sirven para start/stop de servers. Se necesitan client API keys (pcli_... o pacc_... generadas desde Account → API Credentials).
• Reinstall: POST /servers/{id}/reinstall re-ejecuta el install script pero NO cambia la imagen Docker.