Skip to content

Central Hub REST API Reference

The Central Hub exposes a hardened REST API over HTTPS on port 8081.

1. Authentication & Headers

Header Type Description
Cookie Session User session cookie (connect.sid)
X-CSRF-Token CSRF Required on all mutating requests (POST, PUT, DELETE)
Authorization Bearer Used for agent enrollment (Bearer <enrollment-token>)

2. Core Endpoints

Host Inventory

GET /api/hosts

Returns the inventory of configured hosts, connection statuses, and cached metrics. - RBAC: viewer, operator, admin - Response: 

[
  {
    "ip": "192.168.1.100",
    "name": "media-server",
    "status": "online",
    "engine": "podman",
    "agentVersion": "0.9.8"
  }
]

POST /api/hosts

Adds a new host to the inventory. - RBAC: admin - Payload: {"ip": "192.168.1.100", "name": "media-server"}

DELETE /api/hosts/:ip

Removes a host from management. - RBAC: admin

Workload & Container Operations

GET /api/hosts/:ip/status

Queries the host agent for live pods, containers, and Quadlet services. - RBAC: viewer, operator, admin

POST /api/hosts/:ip/actions

Executes an operational lifecycle command on a target container, pod, or service. - RBAC: operator, admin - Payload: 

{
  "target": "service",
  "name": "arrstack",
  "action": "restart"
}

GET /api/hosts/:ip/logs/:unit

Streams systemd journal logs for a specific unit. - RBAC: operator, admin - Query Parameters: lines=100

Agent Distribution & Enrollment

GET /api/agents/install.sh?ip=:ip

Generates the customized agent installation script for remote host onboarding. - Auth: Authorization: Bearer <enrollmentToken>

GET /api/agents/source?ip=:ip

Downloads the agent Python ZipApp binary (stackpilot_agent.pyz).

POST /api/agents/fingerprint?ip=:ip

Registers the agent's self-signed TLS certificate PEM and returns the permanent runtime token. - Payload: {"certPem": "-----BEGIN CERTIFICATE...-----"} - Response: {"agentToken": "sec_tok_..."}