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
Set or get agent display name	POST /display-name/manage
Manage display name on remote agent	POST /agents/{id}/display-name/manage
Run commands on remote agents	WebSocket /agents/{id}/shell
Transfer files to/from agents	POST /agents/{id}/file/*
Test connectivity to all mesh agents	POST /api/mesh-test
Get topology for visualization	GET /api/topology

Base URL

http://localhost:8080

Configure via:

http:
  enabled: true
  address: ":8080"

Category	Purpose
Health	Health checks and readiness probes
Agents	Remote agent status and management
Routes	Route management and triggers
Shell	Remote shell access (interactive and streaming)
File Transfer	File upload/download
Dashboard	Topology data, dashboard overview, and mesh connectivity test

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

Authorization: Bearer <token>

Exempt endpoints (always accessible without a token):

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.

Shell and file transfer endpoints have their own password authentication when configured (shell.password_hash, file_transfer.password_hash).

{
  "error": "error message",
  "code": "ERROR_CODE"
}

Common HTTP status codes: