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.