API Reference

API Reference

HomePilot exposes a REST API and an MCP server. The REST API serves the web UI and direct HTTP clients. The MCP server provides structured tool calls for AI clients.

Authentication

All API requests require an Authorization: Bearer <token> header except:

• GET /health — unauthenticated health check
• POST /auth/tokens — admin-only token creation (requires x-hp-admin-secret header)

Token Scopes

Scope	Permissions
read	All GET endpoints, read-only MCP tools
write	All endpoints including artifact propose/approve
admin	Full access including token management

Creating Tokens

# Full-scope token (read + write + admin)
docker compose exec backend hp token create

# Read-only token
docker compose exec backend hp token create --scope read_only

# JSON output (for scripting)
docker compose exec backend hp token create --output json
# {"token": "hp_abc123...", "scope": "read,write"}

Admin Secret Header

The x-hp-admin-secret header is used for bootstrap operations when no token exists yet:

curl -X POST http://localhost:8000/auth/tokens \
  -H "Content-Type: application/json" \
  -H "x-hp-admin-secret: $HP_ADMIN_SECRET" \
  -d '{"label": "ci-deploy", "scope": "full"}'

REST Endpoints

Health

Method	Path	Auth	Description
GET	/health	none	Health check

Inventory

Method	Path	Auth	Description
GET	/inventory	read	List all hosts and services
GET	/inventory/{host}	read	Show host detail

Artifacts

Method	Path	Auth	Description
GET	/artifacts	read	List artifacts (filter by status, kind, target)
GET	/artifacts/{id}	read	Show artifact detail
POST	/artifacts	write	Propose a new artifact
POST	/artifacts/{id}/approve	write	Approve a proposed artifact
POST	/artifacts/{id}/reject	write	Reject a proposed artifact
POST	/artifacts/{id}/apply	write	Apply an approved artifact
POST	/artifacts/{id}/revoke	write	Revoke an applied artifact
GET	/artifacts/{id}/drift	read	Check drift for an applied artifact

Knowledge Base

Method	Path	Auth	Description
GET	/kb/search	read	Search KB (vector + keyword)

Events

Method	Path	Auth	Description
GET	/events	read	SSE stream of lifecycle events

Auth

Method	Path	Auth	Description
POST	/auth/tokens	admin secret	Create a new API token
DELETE	/auth/tokens/{prefix}	admin	Revoke a token by prefix

MCP Tools

The MCP server exposes these tools. See Architecture for detailed descriptions.

Read-Only Tools (scope: read)

Tool	Description
query_inventory	List hosts/services/networks from DB; optional JSON filter
refresh_inventory	Re-pull inventory from Proxmox API + SSH guests
get_environment_doc	Fused doc for a target: inventory + KB + artifact history
query_artifacts	Find artifacts by status, kind, target, or date
get_artifact_status	Detailed status of one artifact
search_kb	Vector + keyword search over KB notes/policies/decisions
proxmox_api_read	GET-only Proxmox REST call; allowlisted paths only
http_call_read	GET-only call to an adopted service; vault-resolved creds
read_file_on_guest	SFTP file read from guest via jump server
exec_on_guest_readonly	Whitelisted read-only SSH exec (cat, ls, ps, systemctl status...)
check_artifact_drift	Check whether an applied artifact has drifted from desired state

Write Tools (scope: write)

Tool	Description
record_fact	Write note/policy/decision to KB (auto-applied, no approval needed)
propose_artifact	Creates artifact with status: proposed; requires human approval
approve_artifact	Approve a proposed artifact; rate-limited 10/min per caller

Event Payload Schema

All events conform to a unified envelope:

{
  "schema_version": "1",
  "type": "artifact_proposed",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "timestamp": "2026-05-13T10:30:00Z"
}

Event types: artifact_proposed, artifact_approved, artifact_applied, artifact_failed, artifact_revoked, artifact_superseded, drift_detected

Webhook Delivery

Registered webhook endpoints receive events as HTTP POST with HMAC-SHA256 signatures:

• X-Webhook-Signature header contains the HMAC-SHA256 of the request body
• Exponential backoff retry: 1s, 5s, 30s
• Delivery status tracked in webhook_deliveries table

Rate Limiting

Default: 60 requests per IP per minute (HP_RATE_LIMIT). Returns 429 Too Many Requests when exceeded.

CORS

Default: * (all origins). Restrict with HP_CORS_ORIGINS:

HP_CORS_ORIGINS=https://homepilot.example.com,https://admin.example.com

See Also

• Architecture — System architecture and data flow
• Security — Auth model, RBAC scopes, token rotation
• Artifacts — Artifact spec and lifecycle