Agent Hospital API.

Overview.

The Agent Hospital API is designed to be called by agents, not humans. Most integrations use npx @agent-hospital/sidecar heal which handles registration, Ed25519 identity, health collection, repair execution and result reporting automatically. Also available as a ClawHub skill for OpenClaw agents. This page is the under-the-hood reference for operators building custom adapters or auditing the protocol.

Base URL: https://api.agent-hospital.ai

Discovery: GET /.well-known/llms.txt for LLM-readable docs. GET /.well-known/agent-card.json for A2A agent-to-agent discovery (Google A2A v0.2.2). The primary healing flow uses the REST endpoints below; A2A is an optional interop layer.

Authentication.

Agent Hospital uses Ed25519 keypair authentication. On first run, the sidecar registers a host and agent, generates a local Ed25519 keypair, and caches credentials at ~/.agent-hospital/credentials.json.

Each request is signed with a short-lived JWT (60-second TTL) using the private key. The JWT is sent as Authorization: Bearer <jwt>. Header must include typ: "agent+jwt" and alg: "EdDSA".

Legacy agents can also authenticate via x-api-key header. Key rotation is supported via POST /api/v1/agents/:id/rotate-key.

POST/api/v1/heal

Send a health report and workspace files. Returns an AI diagnosis and prescribed repair commands. Requires Ed25519 JWT or API key auth.

Request Body

{
  "framework": "openclaw",
  "report": {
    "framework": "openclaw",
    "host": "my-agent",
    "runtime": { "processAlive": true, "pid": 1234 },
    "gateway": { "alive": true, "port": 18789, "latencyMs": 12 },
    "disk": { "homeDirMb": 200, "totalMb": 370 },
    "integrations": [
      { "type": "slack", "connected": true },
      { "type": "discord", "connected": false, "error": "401" }
    ]
  },
  "fileContents": { "SOUL.md": "...", "openclaw.json": "..." },
  "availableActions": ["restart-daemon", "prune-sessions", "clean-logs"]
}

Response 200

{
  "agentId": "uuid",
  "sessionId": "uuid",
  "diagnosis": {
    "overallStatus": "warning",
    "findings": [
      { "area": "gateway", "severity": "warning",
        "finding": "High latency", "recommendation": "Restart gateway" }
    ],
    "rootCause": "Session accumulation causing memory pressure",
    "confidence": 0.85,
    "narrative": "Your gateway is under memory pressure..."
  },
  "decision": {
    "decision": "more_repairs",  // healed | more_repairs | escalate
    "commands": [
      { "action": "prune-sessions", "whitelisted": true },
      { "action": "restart-daemon", "whitelisted": false }
    ],
    "confidence": 0.85,
    "severity": "warning"
  }
}

POST/api/v1/heal/results

Report the outcomes of executed repair commands. Receive the next decision: more repairs, healed, or escalate. Up to 10 turns per session.

Request Body

{
  "sessionId": "uuid-from-heal",
  "results": [
    { "action": "prune-sessions", "success": true,
      "output": "Deleted 47 files" },
    { "action": "restart-daemon", "success": false,
      "output": "DEFERRED: deferred to post-heal" }
  ],
  "postRepairHealth": { // optional fresh health report }
}

Response 200

{
  "decision": {
    "decision": "healed",    // healed | more_repairs | escalate
    "narrative": "All repairs succeeded. Agent is healthy.",
    "commands": [],
    "confidence": 0.92,
    "severity": "healthy"
  }
}

POST/api/v1/check-in

Stateless health check. Send a health report, get back a status assessment without creating any database records. No auth required. Useful for quick polling.

Response 200

{
  "status": "warning",  // healthy | warning | critical
  "checks": [
    { "area": "gateway", "ok": true },
    { "area": "disk", "ok": false, "detail": "92% used" }
  ]
}

POST/api/v1/heartbeat

Periodic status update from the Go sidecar. Includes integration probes, MCP server health, channel status, cron health, and session metrics. The hospital uses these to detect absence and enrich healing diagnoses.

Related endpoints: POST /api/v1/heartbeat/crash for crash reports with AI diagnosis, POST /api/v1/heartbeat/repair-result for repair outcome callbacks, POST /api/v1/heartbeat/integration-status and POST /api/v1/heartbeat/mcp-status for probe results.

HealthReport.

The health report submitted inside the /heal request body. All fields optional except framework. The sidecar collects these automatically.

• frameworkstringAny framework name — openclaw, hermes, or your own (e.g. vapi, custom). REQUIRED
• profileobjectOptional self-description for custom agents (kind, runtime, description, healthyWhen).
• hoststringAgent hostname.
• versionstringFramework version.
• runtimeobjectprocessAlive, pid, uptimeSeconds.
• gatewayobjectalive, port, latencyMs.
• diskobjecthomeDirMb, sessionsMb, logsMb, totalMb.
• memoryobjectentryCount, storeReachable, lastWrite, sizeBytes.
• modelobjectprovider, apiReachable, authValid, latencyMs.
• integrationsarrayPer-integration: type, connected, latencyMs, error.
• sessionsobjecttotalCount, totalSizeMb, oldestTimestamp.
• logAnalysisobjecttotalErrors, totalWarnings, topErrors, errorRate.
• logsTailstringLast ~100 log lines for symptom matching.
• configSnapshotobjectRedacted agent configuration for diagnosis context.

Repair actions.

Each repair command is parameterless and bound to a framework. Whitelisted actions auto-execute during the heal loop. Manual actions (restarts, port kills) are deferred to post-heal to avoid terminating the session mid-loop.