Gateway API

The gateway is Human’s HTTP server. It serves the Control UI, handles webhooks from messaging channels, and provides a WebSocket control protocol for real-time control.

Starting the gateway

human gateway                      # Default: 127.0.0.1:3000
human gateway --port 8080          # Custom port
human gateway --host 127.0.0.1     # Bind to localhost only

Configuration

Gateway settings in ~/.human/config.json:

{
  "gateway": {
    "enabled": true,
    "port": 3000,
    "host": "::",
    "require_pairing": false,
    "allow_public_bind": false,
    "pair_rate_limit_per_minute": 60,
    "webhook_hmac_secret": null,
    "control_ui_dir": null,
    "cors_origins": []
  }
}

Authentication

WebSocket control connections

• If auth_token is configured, WebSocket clients must send Authorization: Bearer <token> on upgrade.
• If no auth token is set, localhost connections are typically accepted without a token.

Webhook HMAC

Webhooks can verify request integrity with HMAC-SHA256:

• Set webhook_hmac_secret in config or HUMAN_WEBHOOK_HMAC_SECRET
• Incoming webhook requests are checked against the X-Signature header (or similar) using the secret and request body
• Invalid signatures receive 401 Unauthorized

WebSocket control protocol

Connect to ws://<host>:<port>/ws for the control protocol. Messages are JSON-RPC 2.0.

Connect response

After connecting, the server sends a hello-ok message with:

• server.version: e.g. "0.1.0"
• protocol: version number
• features.methods: list of supported RPC methods
• features.sessions, features.cron, features.skills, features.cost_tracking: booleans

Available methods

| Method | Description | | ----------------------- | ------------------------------- | | connect | Initial handshake (implicit) | | health | Health check | | config.get | Get current configuration | | config.schema | Get config schema | | config.set | Update configuration | | config.apply | Apply and persist config | | capabilities | List channels, tools, providers | | chat.send | Send message to agent | | chat.history | Get conversation history | | chat.abort | Abort current generation | | sessions.list | List sessions | | sessions.patch | Update session | | sessions.delete | Delete session | | tools.catalog | List available tools | | channels.status | Channel health | | cron.list | List scheduled jobs | | cron.add | Add cron job | | cron.remove | Remove cron job | | cron.run | Manually trigger a job | | skills.list | List installed skills | | skills.install | Install a skill | | skills.enable | Enable a skill | | skills.disable | Disable a skill | | update.check | Check for updates | | update.run | Apply update | | exec.approval.resolve | Resolve tool approval | | usage.summary | Usage/cost summary | | models.list | List models | | nodes.list | List nodes | | push.register | Register for push | | push.unregister | Unregister from push |

Request format

{
  "type": "req",
  "id": "1",
  "method": "chat.send",
  "params": { "message": "Hello" }
}

Streaming

For chat.send with stream: true, responses arrive as notifications with method: "chat.chunk" and incremental content.

Webhook endpoints

Channels register webhooks under /webhook/<channel> or legacy paths:

| Path | Channel | | ------------------- | ----------------- | | /webhook/telegram | Telegram | | /webhook/discord | Discord | | /webhook/slack | Slack | | /webhook/whatsapp | WhatsApp | | /webhook/line | Line | | /webhook/lark | Lark | | /telegram | Telegram (legacy) | | /slack/events | Slack (legacy) |

Webhook payloads are channel-specific (Telegram Update, Slack event envelope, etc.). The gateway routes them to the appropriate channel handler.

Static files and Control UI

When control_ui_dir is set, the gateway serves static files from that directory. This is used for the built-in Control UI (SPA) for managing the agent, cron, skills, and config.