Open Source|All improvements go through Pull Requests with automated CI checks before review by@Leo-Galli|Join Discord|Contributing guide
API testing

API Testing

Every module in the Aetheris ecosystem exposes API endpoints that can be tested independently. This page lists all available endpoints, expected responses and how to run the tests locally.

Contributors: when submitting a Pull Request that adds or modifies API routes, you must include at least one test case on this page and verify it passes locally before opening the PR. The CI workflow will check that every new route has a corresponding entry here.

Base URL

All endpoints are served by the Aetheris backend. For local development:

http://localhost:8000

For the Vercel demo:

https://aetheris-app-tawny.vercel.app

Authentication

Most endpoints require a Bearer token. Obtain one through the login flow:

TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@aetheris.io","password":"admin"}' | jq -r '.token')

Include the token in subsequent requests:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/...

Hypervisor Modules

Pterodactyl Driver

Tests the Pterodactyl Application API and Client API integration.

EndpointMethodDescriptionExpected
/api/hypervisors/pterodactyl/serversGETList all servers200 + array
/api/hypervisors/pterodactyl/servers/:idGETGet server details200 + object
/api/hypervisors/pterodactyl/nodesGETList nodes200 + array
/api/hypervisors/pterodactyl/nestsGETList nests200 + array
/api/hypervisors/pterodactyl/eggsGETList eggs for a nest200 + array
/api/hypervisors/pterodactyl/servers/:id/consoleGETGenerate WebSocket token200 + token
/api/hypervisors/pterodactyl/servers/:id/startPOSTStart server204
/api/hypervisors/pterodactyl/servers/:id/stopPOSTStop server204
/api/hypervisors/pterodactyl/servers/:id/restartPOSTRestart server204
# List Pterodactyl servers
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/hypervisors/pterodactyl/servers | jq .
 
# Get console token
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/hypervisors/pterodactyl/srv-8f2a/console | jq .

Proxmox VE Driver

Tests the Proxmox VE API v2 integration.

EndpointMethodDescriptionExpected
/api/hypervisors/proxmox/nodesGETList Proxmox nodes200 + array
/api/hypervisors/proxmox/vmsGETList VMs200 + array
/api/hypervisors/proxmox/containersGETList LXC containers200 + array
/api/hypervisors/proxmox/vms/:vmid/startPOSTStart VM204
/api/hypervisors/proxmox/vms/:vmid/stopPOSTStop VM204
/api/hypervisors/proxmox/vms/:vmid/statusGETVM status200 + status
# List Proxmox nodes
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/hypervisors/proxmox/nodes | jq .

VirtFusion Driver

Tests the VirtFusion REST API integration.

EndpointMethodDescriptionExpected
/api/hypervisors/virtfusion/serversGETList servers200 + array
/api/hypervisors/virtfusion/servers/:idGETGet server200 + object
/api/hypervisors/virtfusion/servers/:id/powerPOSTPower action204
/api/hypervisors/virtfusion/servers/:id/consoleGETConsole session200 + URL
# List VirtFusion servers
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/hypervisors/virtfusion/servers | jq .

Billing Module

Invoices

EndpointMethodDescriptionExpected
/api/billing/invoicesGETList invoices200 + array
/api/billing/invoices/:idGETGet invoice200 + object
/api/billing/invoices/:id/payPOSTMark as paid200
/api/billing/invoices/:id/sendPOSTSend invoice email204
/api/billing/summaryGETRevenue summary200 + stats

Subscriptions

EndpointMethodDescriptionExpected
/api/billing/subscriptionsGETList subscriptions200 + array
/api/billing/plansGETList plans200 + array

Payment Gateways

EndpointMethodDescriptionExpected
/api/billing/gateways/stripe/webhookPOSTStripe webhook200
/api/billing/gateways/paypal/webhookPOSTPayPal webhook200
/api/billing/gateways/mollie/webhookPOSTMollie webhook200
# Get revenue summary
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/billing/summary | jq .
 
# List recent invoices
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/billing/invoices | jq 'length'

Server Management

EndpointMethodDescriptionExpected
/api/serversGETList all servers200 + array
/api/servers/:idGETGet server200 + object
/api/servers/:id/startPOSTStart server204
/api/servers/:id/stopPOSTStop server204
/api/servers/:id/restartPOSTRestart server204
/api/servers/:id/destroyPOSTDestroy server204
/api/servers/:id/consoleGETVNC console token200 + ws URL

Node Management

EndpointMethodDescriptionExpected
/api/nodesGETList nodes200 + array
/api/nodes/:idGETGet node200 + object
/api/nodes/:id/resourcesGETNode resources200 + CPU/RAM/disk
/api/nodes/:id/serversGETServers on node200 + array

SFTP Management

EndpointMethodDescriptionExpected
/api/sftp/usersGETList SFTP users200 + array
/api/sftp/usersPOSTCreate user201
/api/sftp/users/:idDELETEDelete user204
/api/sftp/users/:id/togglePOSTEnable/disable200

Scheduled Tasks (Cron)

EndpointMethodDescriptionExpected
/api/cronGETList cron jobs200 + array
/api/cronPOSTCreate cron job201
/api/cron/:idDELETEDelete cron job204
/api/cron/:id/togglePOSTEnable/disable200
/api/cron/:id/runPOSTTrigger manual run202

Whitelabel / Branding

EndpointMethodDescriptionExpected
/api/whitelabelGETGet current config200 + config
/api/whitelabelPUTUpdate config200
/api/whitelabel/themeGETGet theme tokens200 + CSS vars
# Get current whitelabel config
curl -s http://localhost:8000/api/whitelabel | jq '.brand, .theme'

System / Health

EndpointMethodDescriptionExpected
/healthGETHealth check200 + {"status":"ok"}
/api/statusGETSystem status200 + version info
/api/status/versionGETCurrent version200 + semver

Running the Full Test Suite

# Clone the repository
git clone https://github.com/aetheris-project/aetheris-app.git
cd aetheris-app
 
# Install dependencies
cp .env.example .env
docker compose up -d --build
 
# Wait for services to be ready
sleep 30
 
# Run health check
curl -s http://localhost:8000/health
 
# Run automated API tests
npm test
 
# Run hypervisor adapter unit tests
python -m pytest tests/ -v

Adding New Test Cases

When you add or modify an API endpoint:

  1. Add the endpoint to the appropriate table above
  2. Include a curl example that demonstrates the request
  3. Document the expected response shape
  4. Open a Pull Request with the test documentation
  5. The CI workflow will verify that the endpoint exists and returns the expected status code
# Example: adding a test for a new endpoint
# 1. Add to the table above
# 2. Add a curl example:
curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST http://localhost:8000/api/servers \
  -H "Content-Type: application/json" \
  -d '{"name":"test-server","node":"fra-01","egg":1,"docker_image":"ghcr.io/pterodactyl/yolks:ubuntu_22.04"}' \
  | jq .
LoggingBilling engine