API Reference¶

The CharlieHub cluster exposes several APIs for infrastructure management.

Domain Manager API (VM1111:8000)¶

The Domain Manager API provides infrastructure management capabilities.

Base URL: http://REDACTED_IP:8000/api

Infrastructure Endpoints¶

Endpoint	Method	Description
`/api/assets`	GET	List all infrastructure assets
`/api/assets/{vmid}`	GET	Get details for specific asset
`/api/conflicts`	GET	Detect IP and VMID conflicts
`/api/orphans`	GET	Find orphaned entries
`/api/infrastructure/status`	GET	Overall infrastructure status

VMID Management¶

Endpoint	Method	Description
`/api/vmid/next`	GET	Get next available VMID
`/api/vmid/decode`	GET	Decode VMID to node/purpose/sequence
`/api/vmid/validate`	GET	Validate a VMID
`/api/vmid/check`	GET	Check if VMID is in use
`/api/vmid/suggest`	GET	Suggest VMIDs for new VMs

IP Management¶

Endpoint	Method	Description
`/api/ip/next`	GET	Get next available IP address
`/api/ip/used`	GET	List all used IP addresses
`/api/vmid/calculate-ip`	GET	Calculate IP from VMID
`/api/vmid/validate-ip`	GET	Validate IP assignment

Domain Management¶

Endpoint	Method	Description
`/api/domains`	GET, POST	List/create domains
`/api/domains/{id}`	GET, PUT, DELETE	Manage specific domain
`/api/domains/{id}/deploy`	POST	Deploy domain configuration
`/api/deploy-all`	POST	Deploy all domain configs

SSH Management¶

Endpoint	Method	Description
`/api/ssh-clients`	GET	List SSH client configurations
`/api/ssh-targets`	GET	List SSH target hosts
`/api/ssh-targets/sync-names`	POST	Sync names to SSH targets
`/api/deploy-sshpiper`	POST	Deploy SSHPiper configuration

System Endpoints¶

Endpoint	Method	Description
`/health`	GET	Health check endpoint
`/api/system/status`	GET	System status
`/api/metrics/summary`	GET	Metrics summary

Example Usage¶

# Get next VMID for px1 production
curl -s "http://REDACTED_IP:8000/api/vmid/next?node=px1&purpose=prod"

# Decode a VMID
curl -s "http://REDACTED_IP:8000/api/vmid/decode?vmid=1111"

# List all assets
curl -s "http://REDACTED_IP:8000/api/assets" | jq .

# Check for conflicts
curl -s "http://REDACTED_IP:8000/api/conflicts" | jq .

UniFi API (VM1111:8002)¶

Network device monitoring and management.

Base URL: http://REDACTED_IP:8002/api

Endpoint	Method	Description
`/api/devices`	GET	List UniFi devices
`/api/clients`	GET	List network clients
`/api/port-forwards`	GET	List port forwarding rules
`/api/firewall-rules`	GET	List firewall rules
`/api/firewall-groups`	GET	List IP/port groups
`/api/wlans`	GET	List WiFi networks
`/api/networks`	GET	List VLANs/networks
`/api/sync-names`	POST	Sync Proxmox names to UniFi clients
`/api/rogue-check`	GET	Detect unknown devices
`/metrics`	GET	Prometheus metrics

Example Usage¶

# List all devices
curl -s "http://REDACTED_IP:8002/api/devices" | jq .data[]

# Sync Proxmox names to UniFi
curl -X POST "http://REDACTED_IP:8002/api/sync-names"

# Check for rogue devices
curl -s "http://REDACTED_IP:8002/api/rogue-check" | jq .

DDNS API (VM1111:5000)¶

Dynamic DNS update service.

Base URL: http://REDACTED_IP:5000

Endpoint	Method	Description
`/health`	GET	Health check
`/status`	GET	Current DDNS status
`/update`	POST	Force DNS update

BIOS Sync API (Deprecated)¶

Not Migrated

BIOS Sync was on CT3102 and has not been migrated to hub1. This service is deprecated.

Prometheus API (hub1:9090)¶

Metrics querying.

Base URL: https://prometheus.charliehub.net/api/v1 (or http://localhost:9090/api/v1 on hub1)

Endpoint	Method	Description
`/query`	GET	Instant query
`/query_range`	GET	Range query
`/targets`	GET	List scrape targets
`/alerts`	GET	List active alerts

Example Usage¶

# Query current CPU usage (on hub1)
curl -s "http://localhost:9090/api/v1/query?query=node_cpu_seconds_total" | jq .

# Check active alerts
curl -s "http://localhost:9090/api/v1/alerts" | jq .

Interactive API Docs¶

FastAPI services provide interactive documentation:

Domain Manager: http://REDACTED_IP:8000/docs
UniFi API: http://REDACTED_IP:8002/docs