Job Activity Log
| Server | Type | Status | Step | Started | Duration |
|---|---|---|---|---|---|
Dashboard
System overview and job monitoring
Interactive Testing Console
Test API endpoints with live requests
POST
Provision Port for Foreman
/api/v2/port/provision
Configure a switch port for Foreman bare metal provisioning. This looks up the server in NetBox, traces the cable to find the connected switch port, saves the current configuration, and sets the port to access mode with the Foreman VLAN.
Request Body
Server device label from NetBox
VLAN ID (uses default from config if not specified)
Custom port description
WHMCS service ID for tracking
User/system making the request
Examples
{
"device_label": "server-001"
}
{
"device_label": "bm-web-prod-01",
"vlan_id": 100,
"description": "Foreman PXE - OS Reinstall",
"service_id": "12345",
"requested_by": "whmcs-foreman"
}
curl -X POST "http://localhost:8000/api/v2/port/provision" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"device_label": "server-001"}'
Response
Click "Send Request" to see the response
POST
Restore Port Configuration
/api/v2/port/restore
Restore a switch port to its original configuration after provisioning is complete. This finds the backup, restores the original configuration, and marks the backup as restored.
Request Body
Server device label from NetBox
WHMCS service ID (for logging)
Response
Click "Send Request" to see the response
GET
Get Port Status
/api/v2/port/status/{device_label}
Get the current status of a switch port and any associated backups.
Path Parameters
Server device label from NetBox
Response
Click "Send Request" to see the response
GET
List Configuration Backups
/api/v2/port/backups
List all port configuration backups with optional filtering by status and device.
Query Parameters
Response
Click "Send Request" to see the response
GET
Get Backup Details
/api/v2/port/backups/{backup_id}
Get detailed information about a specific configuration backup.
Path Parameters
Response
Click "Send Request" to see the response
DELETE
Delete Backup Record
/api/v2/port/backups/{backup_id}
Delete a backup record from the database. This does NOT restore the port configuration.
Path Parameters
Response
Click "Delete Backup" to see the response
GET
Health Check
/api/v2/health
Basic health check endpoint. No authentication required.
Response
Click "Send Request" to see the response
GET
Get My Server Power Status
/api/v2/tenant-power/power/{device_label}
Query the current power state of your server using tenant IPMI credentials.
Path Parameters
Select your server from the dropdown
Response
Click "Send Request" to see the response
POST
Reboot My Server
/api/v2/tenant-power/reboot
Reboot your server using tenant IPMI credentials. Requires a safety confirmation string.
Request Body
Select your server from the dropdown
Auto-generated safety confirmation string
Force mode performs a hard power off then on. Use only for unresponsive servers.
Response
Click "Reboot Server" to see the response
POST
Power On My Server
/api/v2/tenant-power/power/on/{device_label}
Power on your server using tenant IPMI credentials. This is a safe, non-destructive operation.
Path Parameter
Select your server from the dropdown
Response
Click "Power On" to see the response
POST
Power Off My Server
/api/v2/tenant-power/power/off
Power off your server using tenant IPMI credentials. Supports graceful (ACPI) and force (hard) shutdown modes.
Request Body
Select your server from the dropdown
Auto-generated safety confirmation string
Warning: Force power off can cause data loss and filesystem corruption!
Response
Click "Power Off" to see the response
POST
Update IPMI Credentials
/api/v2/tenant-power/credentials
Update your server's IPMI credentials. The new credentials will be tested against the BMC before being saved.
Request Body
Select your server from the dropdown
New IPMI username (max 16 characters)
New IPMI password (8-20 characters)
Response
Click "Update Credentials" to see the response
GET
Get Server Power Status
/api/v2/server/power/{device_label}
Query the current power state of a server via IPMI/BMC. Returns whether the chassis is powered on, off, or unknown.
Path Parameters
Server device label from NetBox (asset tag or name)
Response
Click "Send Request" to see the response
POST
Reboot Server via IPMI
/api/v2/server/reboot
Reboot a server using IPMI/BMC out-of-band management. Requires a safety confirmation string.
Request Body
Server device label from NetBox
Auto-generated safety confirmation string
Force mode performs a hard power off then on. Use only for unresponsive servers.
Response
Click "Reboot Server" to see the response
POST
Power On Server
/api/v2/server/power/on/{device_label}
Power on a server that is currently off via IPMI/BMC. If the server is already on, this has no effect. This is a safe, non-destructive operation that does not require confirmation.
Path Parameter
Server device label from NetBox
Response
Click "Power On" to see the response
POST
Power Off Server
/api/v2/server/power/off
Power off a server via IPMI/BMC. Supports graceful (ACPI) and force (hard) shutdown modes.
Request Body
Server device label from NetBox
Auto-generated safety confirmation string
Warning: Force power off can cause data loss and filesystem corruption!
Response
Click "Power Off" to see the response
POST
IPMI Hardware Query (Read-Only)
/api/v2/server/query/{device_label}
Query server hardware information via IPMI FRU data. This is a read-only out-of-band query that works even when the server is powered off. Returns basic hardware info as reported by the BMC (varies by vendor). Does not update NetBox.
For comprehensive hardware discovery with NetBox updates:
Use
Use
POST /api/v2/baremetal/lifecycle/{device}/test which boots the server and collects detailed OS-level inventory.
Path Parameter
Server device label from NetBox
Response
Click "Query IPMI" to see the response
GET
List Available Inventory
Admin Only/api/v2/baremetal/inventory/available
List servers available for sale from inventory. Only returns servers with status "inventory" in NetBox, "available-for-sale" tag, that have been wiped and passed hardware testing.
Query Parameters
Filter by NetBox site slug (optional)
Filter by device type slug (optional)
Filter by tag (optional)
Minimum RAM in GB (optional)
Minimum storage in GB (optional)
Response
Click "Send Request" to see the response
POST
Release Server to Inventory
Admin Only/api/v2/baremetal/inventory/release
Release a server back to the available inventory pool. This performs: 1) Disables all switch ports (physical + bond/ae interfaces), 2) Powers off the server (hard power off via IPMI), 3) Updates NetBox device status to "inventory".
Request Body
Server device label (service tag) from NetBox
Auto-generated safety confirmation string
Warning: This will disable all switch ports and power off the server!
Response
Click "Release to Inventory" to see the response
POST
Hardware Discovery
Admin Only/api/v2/baremetal/servers/{identifier}/discover
Boot server into discovery mode to collect hardware inventory. The server will PXE boot into a discovery image that collects CPU, memory, storage, network interfaces, and IPMI/BMC details.
Parameters
The server's service tag or serial number
Creates a discovery job without PXE rebooting. Run the discovery script manually on the server.
Keep server powered on after discovery completes instead of powering off and disabling ports.
Run on Server
SSH into the target server and run these commands as root:
1. Download the discovery script:
curl -o /tmp/hardware-discovery.sh http://foreman.arphost.com/pub/hardware-discovery.sh && chmod +x /tmp/hardware-discovery.sh
2. Run discovery:
Or as a single command:
Requires: dmidecode, smartmontools, nvme-cli, pciutils, jq, curl. storcli is auto-downloaded if a RAID controller is detected.Manual storcli install
# RHEL/CentOS/AlmaLinux/Rocky/FDI: rpm -i http://foreman.arphost.com/pub/storcli/storcli_noarch.rpm # Debian/Ubuntu/Proxmox: curl -o /tmp/storcli.deb http://foreman.arphost.com/pub/storcli/storcli_all.deb && dpkg -i /tmp/storcli.deb
Response
Click "Start Discovery" to see the response
GET
Discovery Lookup by MAC
Admin Only/api/v2/baremetal/discovery/lookup?mac={mac}
Look up an active discovery job by server MAC address. Used internally by hardware-discovery.sh on FDI when kernel cmdline parameters are not available. Returns the callback_url and job_id for the discovery script to use.
Parameters
Any format: colons, hyphens, or bare (0cc47aa40568)
Response
Click "Look Up" to see the response
GET
List Foreman Operating Systems
Admin Only/api/v2/baremetal/foreman/operatingsystems
List all operating systems available in Foreman for provisioning.
Use the id or title from the response as the os_override parameter when provisioning.
Response
Click "Send Request" to see the response
GET
List Foreman Host Groups
Admin Only/api/v2/baremetal/foreman/hostgroups
List all host groups available in Foreman for provisioning.
Use the name or title from the response as the hostgroup parameter when provisioning.
Response
Click "Send Request" to see the response
GET
Get Server Status
Admin Only/api/v2/baremetal/servers/{identifier}/status
Get comprehensive status from all integrated systems: NetBox (device info, lifecycle state, IPs, interfaces), Foreman (build status, host group), WHMCS (service status, client info), IPMI (current power state), and active jobs.
Path Parameters
Server device label (service tag) from NetBox
Response
Click "Send Request" to see the response
POST
Provision Operating System
Admin Only/api/v2/baremetal/servers/{identifier}/provision
Provision a server with an operating system. The server must have NetBox status "inventory" to prevent accidental reinstallation of production servers. This workflow configures switch ports, sets up Foreman, PXE boots the server, and waits for the installation callback.
Request
Server device label (service tag) from NetBox
Foreman host group (default: Compute-Nodes)
Override OS from hostgroup default (optional). Proxmox VE requires iPXE boot.
Root filesystem for Proxmox VE installation.
RAID level for ZFS or Btrfs. RAIDZ options are ZFS only.
Enter device identifier above, then click "Fetch Drives"
Select which drives to install on. If none selected, auto-detects from discovery data.
Pre-load cloud-init VM templates from Foreman (~500-700MB each)
ISOs to download to Proxmox storage. Served from local Foreman server.
Custom hostname (optional, auto-generates from device label if not provided)
Custom root password (optional, min 8 chars). Stored in NetBox device custom field.
WHMCS service ID for billing integration (optional)
Auto-generated safety confirmation string
This will PXE boot the server and reinstall the operating system!
Response
Click "Start Provisioning" to see the response
POST
Wipe Server Disks
Admin Only/api/v2/baremetal/servers/{identifier}/wipe
Securely wipe all disks on a server. Boots server into wipe environment and securely erases all disks. After successful wipe, hardware testing is automatically triggered unless skip_test=true.
Request Body
Server device label (service tag) from NetBox
Auto-generated safety confirmation string
quick: Tries hardware erase, falls back to zeros. secure-erase: Hardware erase only (fails if unsupported).
Warning: This will permanently destroy all data on the server!
Response
Click "Start Wipe" to see the response
POST
Test Server Hardware
Admin Only/api/v2/baremetal/servers/{identifier}/test
Run hardware tests on a server. Boots into FDI test environment and runs CPU stress test (stress-ng), memory test (memtester), SMART health check, disk I/O benchmark (fio, full/burn-in only), and network link verification (ethtool). On success, server is automatically returned to inventory unless auto_return_to_inventory=false.
Request Body
Server device label (service tag) from NetBox
Test suite to run
Creates a test job without PXE rebooting. Run the test script manually on the server.
Run on Server
SSH into the target server and run these commands as root:
1. Download the test script:
curl -o /tmp/hardware-test.sh http://foreman.arphost.com/pub/hardware-test.sh && chmod +x /tmp/hardware-test.sh
2. Run test:
Or as a single command:
Requires: stress-ng, fio, memtester, smartmontools, nvme-cli, ethtool, jq, curl (tools installed automatically via dnf if missing)Response
Click "Start Tests" to see the response
GET
List Baremetal Jobs
Admin Only/api/v2/baremetal/jobs
List all baremetal workflow jobs with optional filtering by status, workflow type, and device.
Query Parameters
Filter by device label (optional)
Response
Click "Send Request" to see the response
GET
Get Job Details
Admin Only/api/v2/baremetal/jobs/{job_id}
Get detailed information about a specific baremetal job including step-by-step logs and progress.
Path Parameters
Job ID to retrieve
Response
Click "Send Request" to see the response
POST
Cancel Job
Admin Only/api/v2/baremetal/jobs/{job_id}/cancel
Cancel a pending or running baremetal job. Only jobs with status "pending" or "running" can be cancelled.
Path Parameters
Job ID to cancel
Response
Click "Cancel Job" to see the response
DELETE
Purge Job History
Admin Only/api/v2/baremetal/jobs/purge
Purge completed job history to remove sensitive data like passwords.
By default, only purges jobs with status "completed", "failed", or "cancelled".
Use include_all=true to purge ALL jobs including pending/running ones.
This is a destructive operation - purged jobs cannot be recovered.
Query Parameters
Only purge jobs for this specific server (optional)
Include pending/running jobs in purge
Type PURGE-JOBS to confirm this destructive operation
Response
Click "Purge Jobs" to see the response
POST
Test Wipe Callback
Debug/api/v2/baremetal/callbacks/wipe-complete
Manually send a wipe completion callback for testing. This simulates what hardware-wipe.sh
sends when disk wipe completes. Use leave_powered_on=true to prevent the server
from being powered off after callback processing.
Request Body
Job ID from the wipe request
Server hostname
Verification result (empty = not verified, triggers troubleshooting mode)
If checked, server will NOT be powered off after callback
Response
Click "Send Callback" to see the response
POST
Test Discovery Callback
Debug/api/v2/baremetal/callbacks/discovery-complete
Manually send a discovery completion callback for testing. This simulates what hardware-discovery.sh
sends when hardware discovery completes. Use leave_powered_on=true to prevent the server
from being powered off after callback processing.
Request Body
Job ID from the discovery request (optional)
Server hostname
Optional status message
If checked, server will NOT be powered off after callback
Response
Click "Send Callback" to see the response
POST
Allocate IP Space for Server
Admin Only/api/v2/admin/ip/allocate
Allocate IPv4 AND IPv6 addresses from site's prefix pools. Creates a /31 (or /30 for Windows) prefix with all IPs populated. Pool selection is automatic: primary pool for new servers, secondary for additional IPs.
Request Body
Server device label (asset tag) from NetBox. Site is auto-detected.
IPv4 prefix size (ignored if IPv6 Only is checked)
Allocate IPv6 only, derived from existing primary IPv4. Device must have primary IPv4.
Use when IPv6 pools are not configured
Response
Click "Allocate IP Space" to see the response
POST
Assign IP to Device Interface
Admin Only/api/v2/admin/ip/assign
Assign a specific (already allocated) IP to a device interface. Use for manual IP assignment or moving IPs between servers.
Request Body
Server device label (asset tag)
Interface to assign IP to (default: bond0)
IPv4 address with CIDR notation
IPv6 address with CIDR notation
Set as device's primary IP
Response
Click "Assign IP" to see the response
POST
Release Server IP Space
Admin Only/api/v2/admin/ip/release
Release a server's IP allocation back to the pool. Deletes IP addresses assigned to the device and clears primary IP references.
Request Body
Server device label (asset tag). Click "Fetch IPs" to load available IPs.
Choose which IPs to release
Click "Fetch IPs" to load available IPs
Check the IPs you want to release
Response
Click "Release IP Space" to see the response
POST
Allocate Shared Prefix for VLAN
Admin Only/api/v2/admin/ip/vlan/allocate
Allocate a shared prefix (≥/29) for a public VLAN that multiple servers can share. Use for server clusters or customers who need IP mobility between servers.
Request Body
VLAN ID to allocate for
Site to allocate from
IPv4 prefix size
⚠️ This endpoint is not yet implemented
Response
Not yet implemented
POST
Assign IP from VLAN Prefix
Admin Only/api/v2/admin/ip/vlan/assign
Assign the next available IP from a shared VLAN prefix to a server.
Request Body
VLAN ID identifying the shared prefix
Server to assign IP to
⚠️ This endpoint is not yet implemented
Response
Not yet implemented
POST
Release IP from VLAN
Admin Only/api/v2/admin/ip/vlan/release
Release a single server's IP from a shared VLAN prefix. Does NOT delete the prefix - only removes the server's IP assignment.
Request Body
VLAN ID identifying the shared prefix
Server to release IP from
⚠️ This endpoint is not yet implemented
Response
Not yet implemented
GET
List All Users
Admin Only/api/v2/auth/admin/users
List all users in the system with their API key counts. Requires admin privileges and JWT authentication.
Response
Click "Send Request" to see the response
GET
Get User Details
Admin Only/api/v2/auth/admin/users/{user_id}
Get detailed information about a specific user including their API keys. Requires admin privileges.
Path Parameters
User ID to retrieve
Response
Click "Send Request" to see the response
PATCH
Update User Permissions
Admin Only/api/v2/auth/admin/users/{user_id}
Update a user's account settings such as active status and admin privileges. Note: You cannot revoke your own admin status or deactivate your own account.
Request
User ID to update
Whether the user account is active
Whether the user has admin privileges
Response
Click "Update User" to see the response
GET
List User's API Keys
Admin Only/api/v2/auth/admin/users/{user_id}/keys
List all API keys for a specific user. Requires admin privileges.
Path Parameters
User ID whose keys to list
Response
Click "Send Request" to see the response
PATCH
Update User's API Key
Admin Only/api/v2/auth/admin/users/{user_id}/keys/{key_id}
Update an API key's settings including active status and scopes.
Request
User ID who owns the key
API Key ID to update
Whether the API key is active
Available: admin:*, power:read, power:write, port:read, port:write, backups:read, backups:manage, keys:manage
Response
Click "Update Key" to see the response
DELETE
Delete User's API Key
Admin Only/api/v2/auth/admin/users/{user_id}/keys/{key_id}
Permanently delete an API key for any user. This cannot be undone.
Path Parameters
User ID who owns the key
API Key ID to delete
Response
Click "Delete Key" to see the response
POST
Create New User
Admin Only/auth/admin/users
Create a new user account. The user can be assigned to a tenant and given admin privileges.
Request Body
User email address
Optional username
User password (min 8 characters)
Optional tenant ID to assign user to
Grant tenant admin privileges
Grant global admin privileges
Response
Click "Create User" to see the response
POST
Change User Password
Admin Only/auth/admin/users/{user_id}/change-password
Change any user's password. The user will need to use the new password on their next login.
Parameters
User ID to change password for
New password (min 8 characters)
Response
Click "Change Password" to see the response
POST
Create API Key for User
Admin Only/auth/admin/users/{user_id}/keys
Create an API key for any user. The full key is shown only once!
Parameters
User ID to create key for
Name for the API key
Comma-separated list of scopes
Optional expiration in days (1-365)
Response
Click "Create Key" to see the response
POST
Impersonate User
Admin Only/auth/admin/impersonate/{user_id}
Generate a temporary token to act as another user. The token expires in 1 hour and cannot be refreshed. Cannot impersonate yourself or other admins.
Parameters
User ID to impersonate
Response
Click "Start Impersonation" to see the response
GET
Audit Logs
Admin Only/auth/admin/audit-logs
View audit logs of admin actions. Logs auto-delete after 60 days.
Filters
Filter by admin who performed action
Filter by target user
Filter by action type
Maximum results to return
Response
Click "Load Audit Logs" to see the response
POST
Sync from NetBox
Admin Only/api/v2/tenants/sync-netbox
Synchronize tenants and users from NetBox. This imports tenants and their contacts as users, creating API keys with appropriate default scopes.
Sync Options
This will sync all tenants from NetBox and create/update users based on contacts assigned to each tenant. Existing users will be updated, new users will be created with passwords stored in NetBox.
Response
Click "Sync from NetBox" to run the sync
GET
Tenant Activity Logs
Tenant Admin/api/v2/tenants/{tenant_id}/activity-logs
View all API activity for users in your tenant. Logs auto-delete after 60 days. Only tenant admins can view these logs.
Filters
Filter by specific user
Filter by endpoint pattern
Maximum results to return
Activity Logs
Click "Load Activity Logs" to see the response
GET
Tenant Devices
Tenant Admin/api/v2/tenants/{tenant_id}/devices
View all devices assigned to your tenant from NetBox. Shows server details including status, platform, rack location, and IP information.
Devices
Click "Load Devices" to see your tenant's servers
POST
Change My Password
/auth/change-password
Change your own password. You must provide your current password for verification.
Request Body
Your current password
New password (minimum 8 characters)
Response
Click "Change Password" to see the response
GET
My API Keys
/auth/keys
List all your API keys. You can also create new keys and revoke existing ones.
Create New API Key
Name for the API key
Comma-separated list of scopes
Optional expiration in days (1-365)
Response
Click "Load My Keys" to see your API keys
GET
Manage IPv4 PTR Records
/api/v2/dns/records?family=ipv4
View, create, and delete IPv4 PTR (reverse DNS) records for your IP addresses.
Click "Refresh" to load your IPv4 PTR records.
Set PTR Record
GET
Manage IPv6 PTR Records
/api/v2/dns/records?family=ipv6
View, create, and delete IPv6 PTR (reverse DNS) records for your IP addresses.
Click "Refresh" to load your IPv6 PTR records.
Set PTR Record
GET
Reverse Name Preview
/api/v2/dns/reverse-name/{ip}
Preview the reverse DNS name for any IP address. Shows the in-addr.arpa (IPv4) or nibble-format ip6.arpa (IPv6) name and whether a matching reverse zone exists.
Parameters
IPv4 or IPv6 address to generate reverse name for
Response
Enter an IP and click preview to see its reverse DNS name
GET
List Reverse Zones
Admin Only/api/v2/dns/zones
List all reverse DNS zones configured on the PowerDNS server.
Response
Click "Load Zones" to list reverse DNS zones
POST
Create Reverse Zone
Admin Only/api/v2/dns/zones
Create a new reverse DNS zone. Examples: 20.109.78.in-addr.arpa (IPv4 /24),
c.d.4.f.2.0.6.2.ip6.arpa (IPv6 /32).
Request Body
Zone name (trailing dot optional)
Zone replication type
One nameserver FQDN per line (with trailing dots)
Response
Submit the form to create a reverse zone
GET
Device DNS Records
Admin Only/api/v2/dns/records/{device_label}
List all PTR records for IPs assigned to a specific device. Also shows IPs without PTR records.
Parameters
Device asset tag from NetBox
Response
Enter a device label and click load
GET
My IPv4 Space
/api/v2/ips/prefixes
View and manage your IPv4 address space. Select a prefix to see all addresses, claim available IPs, and update descriptions.
Select a prefix to view IP addresses.
GET
My IPv6 Space
/api/v2/ips/prefixes
View and manage your IPv6 address space. Select a prefix to see existing addresses, claim IPs, and update descriptions.
Select a prefix to view IP addresses.
User Management
Manage users and their access
All Users
| ID | Name | Tenant | Status | Role | Actions | |
|---|---|---|---|---|---|---|
| Click "Refresh" to load users | ||||||
Edit User
User Details
API Keys
Loading...
Create API Key
Leave empty for no expiration
Key Created! Copy this now - it won't be shown again:
Edit API Key Scopes
Change Password
User Management
Manage users in your tenant
Tenant Users
| ID | Name | Status | Role | Scopes | Actions | |
|---|---|---|---|---|---|---|
| Loading users... | ||||||
Create Tenant User
Leave blank to auto-generate a password
Grant tenant admin privileges to this user
Leave unchecked to use role-based defaults.
Edit User
User Details
Assign specific permissions. Check "Use role defaults" to reset.
API Keys
API Key Created - Copy Now!
Loading API keys...
Edit API Key Scopes
Change Password
Edit My Profile
User Details
Tenant Admin
API Keys
Leave empty for no expiration
Key created! Copy now — won't be shown again:
Loading...
My API Keys
Manage your API keys for programmatic access.
Leave empty for no expiration
Key created! Copy this now - it won't be shown again:
Loading...
Sub-User Management
Manage reseller client accounts and resource assignments
Sub-Users
| ID | Name | Status | Scopes | Resources | Actions | |
|---|---|---|---|---|---|---|
| Loading sub-users... | ||||||
Create Sub-User
Leave blank to auto-generate. Auto-generated password will be shown after creation.
Permissions for this sub-user. Defaults are pre-selected.
Sub-user created successfully!
Generated password (copy now):
Edit Sub-User
User Details
API Keys
API Key Created - Copy Now!
Loading API keys...
Change Sub-User Password
Resource Assignments
Loading...
Loading...
Loading...
Loading...