HTTP endpoints

A running Hub listens on a small set of ports. Only the edge is meant to face users. Everything else binds 127.0.0.1 and is reached through the edge or by processes on the same machine.

1. Browser or client
2. Edge (PORT)
3. Bridge (loopback)
4. Hub runtime

The Slack adapter uses Socket Mode and opens no port. In a gateway, each Hub's bridge gets its own loopback port and the edge routes by Hub, as described in gateway routes.

EdgeCopy Anchor Link

The edge binds the public port, streams responses and relays websockets. For a single Hub (hubzoid run) it forwards:

<hub> is the slug of the Hub folder name, or HUBZOID_HUB_SLUG. /portal covers the Console and its API, the artifact viewer, public links and connection pages. The bridge's /v1, /uploads and /healthz routes are never forwarded. The edge also serves /hubzoid-portal-navigation.js, a small script that links the web chat to the Console.

Rules the edge applies before it forwards a request:

• A path with a . or .. segment is refused with 400, so no path can climb out of a forwarded prefix.
• Client-sent X-Hubzoid-* and X-OpenWebUI-* headers are removed before forwarding. Only trusted local callers set identity headers.
• In a gateway, a request that changes a migrated Hub's model access in the web chat (POST, PUT, PATCH or DELETE under /api/v1/models/) is refused with 403. Access for that Hub is managed in the Console.
• With HUBZOID_LOCK_OWUI_ACCESS_UI=true, writes to /api/v1/groups (or the prefixes in HUBZOID_OWUI_LOCKED_PREFIXES) are refused with 403.
• With HUBZOID_HIDE_OWUI_USERS on, the web chat's user list redirects to the Console's People page, its Admin Panel opens on Settings > Integrations, and browser writes to its account admin API are refused with 403. When every agent is managed in the Console, its whole Users section, Groups included, opens Settings > Integrations.
• The web chat's model list (GET /api/models) is filtered by Hubzoid's entry decision for the signed-in person, read from /portal/api/chat-access, including for chat administrators. When that check cannot be made, the list is refused rather than shown unfiltered.
• During a connection journey, the edge sends the browser back to the journey's /portal/connect/<id>/done page after the provider's consent, instead of the web chat's home page.
• An upstream that is not reachable returns 502.

With HUBZOID_DISABLE_EDGE=1 there is no edge: the web chat binds the public port and none of the bridge paths are reachable from outside.

Gateway routesCopy Anchor Link

hubzoid gateway runs one edge for all Hubs:

BridgeCopy Anchor Link

The bridge serves one Hub. Its API key check compares Authorization: Bearer <key> with BRIDGE_API_KEYS.

POST /v1/chat/completionsCopy Anchor Link

The endpoint the web chat, Slack adapter and inbound receiver use. It is loopback only, so a client elsewhere reaches the Hub through one of those surfaces or through MCP.

• Body. messages is required. stream: true returns server-sent events in the OpenAI chunk format, ending with a usage chunk and data: [DONE]. Without it the reply is one JSON chat.completion object with usage. Attachments may be sent as data: URLs in message content, and each is saved to the chat's uploads.
• Chat id. Files and history are scoped to a chat id taken from, in order: chat_id, metadata.chat_id, metadata.conversation_id, the X-Hubzoid-Chat-Id header, user, or a hash of the first user message.
• Identity headers. X-OpenWebUI-User-Email or X-Hubzoid-User names the caller, X-Hubzoid-Surface names the surface (default owui), and X-Hubzoid-Groups adds groups. They are trusted because only holders of the bridge key can call the bridge.

Using this API from your own code is covered in OpenAI-compatible API.

GET /artifacts/{chat_id}/{filename}Copy Anchor Link

Links written by write_artifact carry a signature in ?t=, plus an expiry in ?e= when HUBZOID_ARTIFACT_LINK_TTL is set. A request without a valid signature must present a bridge key, and the public default key dev is refused on this route. Files are served inline.

POST /uploads/{chat_id}/{filename}Copy Anchor Link

The raw request body is the file. The type comes from Content-Type, or from the file name when that header is missing or generic. A body over HUBZOID_MAX_UPLOAD_BYTES returns 413. The response is {"chat_id": ..., "filename": ..., "size": ...}.

MCP serverCopy Anchor Link

With MCP_SERVER=true, the bridge serves the Hub over MCP Streamable HTTP at /mcp. The edge exposes it at /mcp for a single Hub and at /b/<hub>/mcp in a gateway. Each request is self-contained (stateless).

Connecting Claude Code, Cursor and other clients is covered in connect an assistant.

Console APICopy Anchor Link

The Console's web app is served at /portal/ and calls a JSON API under /portal/api. The same API is the management API for scripts. A caller authenticates in one of two ways, and a client-sent identity header is never trusted:

• The web chat's session. The bridge verifies the token cookie with the web chat and uses the verified email. Requests that change anything must come from the same origin, checked with the Origin or Referer header.
• An Open WebUI API key, sent as Authorization: Bearer sk-.... It is checked against the web chat's key table, the caller acts as the key's owner under the same rules, and no Origin is needed. Any other Authorization value is ignored. Keys can be created where Open WebUI API keys are turned on, which MCP_SERVER=true does.

Most endpoints need manage_access for the organization or for at least one Hub, and every response is limited to the Hubs the caller manages. One authorization service decides every change. A refusal has a safe message and a stable code, for example {"detail": "Outside your access: ...", "code": "outside_ceiling"}.

A change on a Hub with group-based access is refused with code legacy. An expected_revision that no longer matches returns 409, so an edit built on stale data is never applied. New access for everyone signed in (*) is refused. Page sizes are capped at 200. What each screen shows is described in the Console overview.

Artifact viewerCopy Anchor Link

Published artifacts are served under /portal by any bridge. Access is decided on every request, so a removed share or link stops working at once. No Console rights are involved: owners manage their own artifacts here.

HTML artifacts are served with a sandbox policy that gives them their own opaque origin, so their scripts cannot read the session or call the app. They make no network requests unless HUBZOID_ARTIFACT_ALLOW_ORIGINS names origins they may load from. File types the viewer does not preview are only downloaded. The chat download route /artifacts/{chat_id}/{filename} cannot reach published artifacts.

Connection pagesCopy Anchor Link

With HUBZOID_CONNECT_JOURNEY=true, the connect_account tool sends a person a link to /portal/connect/<id>. Every page needs the web chat session of the person who asked. A signed-out person is sent to sign in and back to the link, and another account gets 403, which is recorded in the access log.

Inbound receiverCopy Anchor Link

The receiver runs with hubzoid inbound run or with hubzoid run --whatsapp, --telegram or --webhook. Each surface is served only when its variables are set.

A request that fails verification gets 403 before anything else runs. WhatsApp and Telegram senders must also be in the Hub's roster, identity/access.csv or identity/access.py.

Generic webhookCopy Anchor Link

• Shared secret mode (default). Send the secret as Authorization: Bearer <secret> or X-Webhook-Secret: <secret>. A ?token= query parameter is also accepted, but it lands in access logs, so prefer a header.
• HMAC mode (WEBHOOK_INBOUND_HMAC=true). Send X-Signature-256: sha256=<hex> or GitHub's X-Hub-Signature-256, the HMAC-SHA256 of the raw body with the secret.
• Storage. Each verified delivery is written to <hub>/.inbound/webhooks/<name>/ as one JSON file with the surface, name, receive time, query, content type and body. A non-JSON body is kept as text. The response is 200 ok once stored and 500 when storage failed, so the sender retries.
• Duplicates. A delivery is recognized by X-GitHub-Delivery, X-Delivery-Id, X-Webhook-Id, Idempotency-Key or X-Request-Id, or else by an identical body in the same or the previous ten-minute window. A repeat answers 200 duplicate and is not stored again. A copy that arrives while the first is still being stored gets 503, so the sender retries later.

A markdown task with on_webhook: <name> runs when events wait in that inbox. See webhooks.

Next stepsCopy Anchor Link

Read this page as Markdown