HTTP API Reference

Query agent status, trigger actions, and build integrations. Every agent exposes an HTTP API for monitoring and management.

Quick reference:

I want to...	Endpoint
Check if an agent is running	GET /healthz
See all agents in the mesh	GET /agents
Push route updates immediately	POST /routes/advertise
Add, remove, or list dynamic routes	POST /routes/manage
Manage routes on a remote agent	POST /agents/{id}/routes/manage
Explain which route an agent would pick	POST /route/trace
Trace route selection on a remote agent	POST /agents/{id}/route/trace
Set or get agent display name	POST /display-name/manage
Manage display name on remote agent	POST /agents/{id}/display-name/manage
Add, remove, or list dynamic peer connections	POST /peers/manage
Manage peers on a remote agent	POST /agents/{id}/peers/manage
Add, remove, or list dynamic transport listeners	POST /listeners/manage
Manage listeners on a remote agent	POST /agents/{id}/listeners/manage
Run commands on remote agents	WebSocket /agents/{id}/shell
Transfer files to/from agents	POST /agents/{id}/file/*
Gracefully stop an agent	POST /shutdown
Stop a remote agent	POST /agents/{id}/shutdown
Test connectivity to all mesh agents	POST /api/mesh-test
Probe a Muti Metroo listener (dial + handshake)	POST /api/probe
Probe a listener from a remote agent	POST /agents/{id}/probe
Get topology for visualization	GET /api/topology

Base URL

http://localhost:8080

Configure via:

http:
  enabled: true
  address: ":8080"

Endpoint Categories

Category	Purpose
Health	Health checks and readiness probes
Agents	Remote agent status and management
Routes	Route management and triggers
Management Commands	Run management commands (interactive and streaming)
File Transfer	File upload/download
Dashboard	Topology data, dashboard overview, and mesh connectivity test
Probe	Connectivity probe (dial + handshake) for individual listeners

Authentication

Bearer Token (API-wide)

When http.token_hash is configured, all non-health endpoints require a bearer token:

Authorization: Bearer <token>

Exempt endpoints (always accessible without a token):

• /health, /healthz, /ready -- health probes
• /, /logo.png, /notfound.png -- splash page assets

Query parameter fallback for WebSocket clients that cannot set headers:

ws://localhost:8080/agents/{id}/shell?token=<token>

CLI usage:

# Flag
muti-metroo status --token my-secret-token

# Environment variable
export MUTI_METROO_TOKEN=my-secret-token
muti-metroo status

Generate a token hash:

muti-metroo hash
# Paste the output into config:
# http:
#   token_hash: "$2a$10$..."

When token_hash is empty (default), no API-wide authentication is enforced.

Management-key Authorization

Privileged operations -- management commands, file transfer, every dynamic mutation (routes, peers, forward listeners and endpoints, hosts, display name), and sleep/wake -- additionally require an Ed25519 signature from the mesh management signing key on top of the bearer token. See Management Key Configuration for the full scope and the deployment model. There is no separate per-feature password for these operations.

Response Formats

• JSON: Most endpoints return JSON
• Plain text: Health checks return plain text
• Binary: File downloads return binary data

Error Responses

{
  "error": "error message"
}

Common HTTP status codes:

• 200 OK: Success
• 400 Bad Request: Invalid request
• 401 Unauthorized: Authentication failed
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error