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.