HTTP endpoints

Every route a running Hub serves. Only the edge faces people. Everything else binds 127.0.0.1 and is reached through the edge or by Hubzoid's own 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. With several Hubs, each Hub's bridge gets its own loopback port and the edge routes by Hub, as described in routes for several Hubs. With sign-in off, hubzoid run refuses a network --host unless HUBZOID_ALLOW_UNAUTHENTICATED_NETWORK=true, because every visitor would act as the local owner.

API referenceCopy Anchor Link

A running Hub serves a reference of its public API at /docs, with the schema at /openapi.json. It is titled Hubzoid API and carries the installed version. Signed-in people also reach the schema at /api/openapi.json. The SDK guide the Hubzoid API (opens in a new tab) has examples.

• Public API only. The web app's own routes, Settings (/portal) and administration are left out of the reference.
• Address. Each agent has its own base, https://<your hub>/b/<agent>. The first agent also answers at the root. GET /b/<agent>/v1/models names the model id to send.
• Sign-in. Authorization: Bearer hzp_..., a personal API key a person creates in Settings under their account's security. It acts as that person, within their access, and may be limited to some agents. A key never signs in, changes passwords or two-step sign-in, creates other keys, or answers an approval or a question. An embedded app uses its short pass instead.
• On a laptop with sign-in off, the agents answer on http://127.0.0.1:3080 with no key.
• Errors are JSON with a detail. 401 means no valid credential, 403 not allowed, 409 a conflict with a newer change, 422 an invalid body, 503 the agent is restarting.

Call any route as yourself from a terminal with hubzoid api.

EdgeCopy Anchor Link

The edge binds the public port and streams responses. Before it forwards anything:

• A path with a . or .. segment is refused with 400, so no path can climb out of a forwarded prefix.
• Client-sent X-Hubzoid-* identity headers are removed. Only Hubzoid's own processes set identity headers, on loopback.
• It keeps no cookies between visitors, and asserts X-Forwarded-Proto: https upstream when the declared public URL is HTTPS and the request carries no scheme of its own.
• An upstream that is not reachable returns 502. With several Hubs, a request body of up to 64 KiB is retried on the next bridge when the first refuses the connection.
• GET /healthz/workflows is answered by the edge itself. See workflow health.

A single Hub's edge sends every path to the bridge, except:

<hub> is the slug of the Hub folder name, or HUBZOID_HUB_SLUG. The bridge then serves the web app, Settings at /settings, MCP at /mcp, chat downloads and published artifacts. The edge also drops a client-sent X-Forwarded-Prefix header. HUBZOID_DISABLE_EDGE has no effect.

Routes for several HubsCopy Anchor Link

A hubzoid run of several Hubs runs one edge for all of them. Paths under /b/<hub> go to that Hub's bridge with the /b/<hub> prefix removed:

The edge adds X-Forwarded-Prefix: /b/<hub> when it removes the prefix, so the bridge knows the call is scoped to that Hub. A chat call that reaches another Hub's bridge gets 409 with the code wrong_hub. Falling back to another bridge is not high availability for the deployment itself.

Workflow healthCopy Anchor Link

A Hub is unhealthy when its workflow settings are invalid, or when workflows are enabled and no engine holds a live, ready lease. The edge also sends the stale and recovered alerts.

Web appCopy Anchor Link

The bridge serves the Hubzoid web app: chat at /, sign-in at /auth and Settings at /settings, one bundle and one sign-in. Every route below needs a signed-in person unless the table says otherwise. With sign-in off (HUBZOID_AUTH unset), every request is the local owner, admin@localhost.

• Session. An opaque hz_session cookie, stored on the server only as a digest. It lasts at most HUBZOID_SESSION_DAYS (30) and ends after HUBZOID_SESSION_IDLE_DAYS (7) without use. Password, role and status changes, blocks and deletion end a person's sessions.
• Same origin. Every request that changes something must carry an Origin or Referer that matches the request's host or one of the deployment's addresses (HUBZOID_PUBLIC_URL, HUBZOID_ALLOWED_ORIGINS), or it is refused with 403.
• Errors have the shape {"detail": {"code": "...", "message": "..."}}.

PagesCopy Anchor Link

Sign-in APICopy Anchor Link

• Password sign-in, sign-up and password changes answer 409 with sign_in_off while sign-in is off. With ENABLE_LOGIN_FORM or ENABLE_PASSWORD_AUTH set to false, password sign-in answers 403.
• Failed attempts are limited per client address and per email: HUBZOID_AUTH_MAX_FAILURES (10) in 15 minutes locks for 15 minutes with 429 and Retry-After. Per-address limits depend on X-Forwarded-For from a TLS proxy.
• One-time links last HUBZOID_LINK_HOURS (72) and work once. Administrators create them in Settings or with hubzoid admin. Nothing is emailed.
• Register <your address>/oauth/<provider>/callback with each provider, for every address people use. See authentication.

Chat APICopy Anchor Link

• Conversations are private to their owner. Anyone else gets 404.
• Starting work needs Use this agent (use_hub) on that agent. A reply runs on the server, so closing the page does not stop it. One reply runs per conversation at a time, and another request answers 409 with run_in_progress.
• Each file is limited to HUBZOID_MAX_UPLOAD_BYTES (25 MiB) and each message to HUBZOID_MAX_FILES_PER_MESSAGE files (10). A larger upload answers 413.

Agents, branding and connectionsCopy Anchor Link

The connection routes are also served under /portal/api/connections. With sign-in off and no HUBZOID_PUBLIC_URL or HUBZOID_ALLOWED_ORIGINS, they answer only requests addressed to a loopback address (403 with untrusted_host), so another web page cannot act as the local owner. See tools and connectors.

Chat inside your appCopy Anchor Link

The AG-UI endpoint for apps that embed an agent's chat, registered under apps: in hubzoid.yaml. Every route takes Authorization: Bearer <pass or app JWT>. With several Hubs, prefix the agent's address, /b/<agent>.

• People. No Hubzoid account is created. A person's chats are kept under a private id made from the app and their user id, and nobody can reach someone else's chat by naming its id.
• History is Hubzoid's. Only the new user message is read from messages. One reply runs per chat at a time, and a second answers 409 with run_in_progress.
• Approvals and questions come as RUN_FINISHED with an interrupt outcome. Answer with a new run whose resume holds the decision.
• Page context in AG-UI context, or forwardedProps.hubzoid.page, reaches the agent marked as data, at most 4,000 characters, and never decides access.
• Security. Only the app's origins may call from a browser. These routes never read a Hubzoid cookie, and a request carrying both answers 400 with ambiguous_credentials. A pass opens only these routes. Refused tokens are rate-limited per address and runs per person.
• Limits of this release. Client-declared AG-UI tools are ignored, and messages are text only.

Set up an app with hubzoid embed. The SDK guide chat inside your app (opens in a new tab) has the server and page code.

BridgeCopy Anchor Link

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

The bridge also serves the web app, the MCP server, the Settings API, the artifact viewer, the connection pages and the workflow webhook receiver.

POST /v1/chat/completionsCopy Anchor Link

The endpoint the Slack adapter and the inbound receiver use, with a bridge key on loopback. Your own programs call it through the edge with a personal API key, and it runs as that key's owner. With a key the answer holds the answer text only, without tool activity or thinking.

• 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. X-Hubzoid-User names the caller, X-Hubzoid-Surface names the surface and X-Hubzoid-Groups adds groups. They count only when a valid X-Hubzoid-Assertion covers exactly their values: an HMAC made with the deployment key by another Hubzoid process, for this Hub, in the last 60 seconds. Without one the request is anonymous, so a bridge key alone cannot act as somebody else. user in the body is never an identity.

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= and an expiry in ?e=. They last HUBZOID_ARTIFACT_LINK_TTL seconds, 7 days by default. The signed-in owner of the conversation can download its files even after the link expires. A request with neither 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": ...}. The web app attaches files through /api/conversations/<id>/files instead.

MCP serverCopy Anchor Link

With MCP on, 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 with several Hubs. Each request is self-contained (stateless). MCP is on for hubzoid run when the public address is loopback or HTTPS, at <address>/mcp, unless the Hub sets MCP_SERVER itself. With several Hubs it is on only for Hubs whose own .env sets MCP_SERVER=true. MCP_PUBLIC_URL must be that public /mcp address, HTTPS except on loopback.

OAuth endpointsCopy Anchor Link

Access tokens last up to 10 minutes. Refresh tokens and grants last up to 30 days, and a refresh token works once. With several Hubs the same paths sit under /b/<hub>, for example /b/<hub>/mcp/oauth/connections, and the two metadata documents are at /.well-known/oauth-protected-resource/b/<hub>/mcp and /.well-known/oauth-authorization-server/b/<hub>/mcp/oauth.

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

Settings APICopy Anchor Link

Settings is served at /settings and calls a JSON API under /portal/api. The same API is the management API for scripts. A client-sent identity header is never trusted. A caller authenticates with:

• The session. The Hubzoid session cookie. Requests that change anything must come from the same origin.

Most endpoints need Manage access (manage_access) for the organization or for at least one agent. Each response is limited to the agents the caller manages. Organization administrators hold it for the organization. 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 signed-out caller gets 401, and a signed-in person who manages nothing gets 403 on these endpoints.

In the tables, manager means a person with Manage access somewhere, organization admin means an organization administrator, and signed in means any signed-in person.

Agents and accessCopy Anchor Link

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. Nobody can change their own access. Page sizes are capped at 200.

People and accountsCopy Anchor Link

Workflows, schedules and reportsCopy Anchor Link

With several Hubs, the eval endpoints redirect to the agent's own bridge under /b/<hub>/portal/api.

ConnectorsCopy Anchor Link

Connectors are files, connectors/<id>.yaml. Adding, changing, deleting and offering one answer 409 with in_app_editing_off unless browser editing is on, and never write files that come from an image. People's own connections are under /portal/api/connections with the same routes as /api/connections. The connector endpoints need the same origin for changes.

Your own workCopy Anchor Link

These answer any signed-in person, for their own work only. A schedule that is not theirs answers 404.

Activity and usageCopy Anchor Link

Change requestsCopy Anchor Link

What each section shows is described in the Settings 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 administration rights are involved: owners manage their own artifacts here. Identity comes from the session, verified on the server.

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.

Live reportsCopy Anchor Link

A workflow that publishes with a key keeps one link per report that always shows the newest copy.

Company linksCopy Anchor Link

A company link lets anyone whose sign-in email is at HUBZOID_SHARE_DOMAINS read one report after signing in. A reader who does not use the agent becomes a reader-only account with no agent access.

Public linksCopy Anchor Link

Connection pagesCopy Anchor Link

When an agent's connect_account tool sends a person a link, it points to /portal/connect/<id>. Every page needs the session of the account that 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.

Links expire after HUBZOID_CONNECT_TTL seconds (600 by default).

Inbound receiverCopy Anchor Link

The receiver starts with its Hub in hubzoid run when a file in the Hub's channels/ folder turns on WhatsApp, Telegram or the generic webhook. Each surface is served only when its variables are set.

A request that fails verification gets 403 before anything else runs. A WhatsApp or Telegram sender must be known: by the phone number an organization administrator recorded for them in Settings, or by the Hub's own lookup in 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.

Workflow webhooksCopy Anchor Link

A code workflow declared with @workflow(on_webhook="<name>") starts from a webhook named in the webhooks: section of workflows/settings.yaml. The Hub's own bridge receives it, whether the Hub runs alone or with others.

<NAME> is the webhook name in upper case with - written as _. Each webhook verifies in one of three ways:

• verify: header (default). The secret, unchanged, in the header named by header (X-Hook-Secret when none is named).
• verify: hmac. sha256= and the hex HMAC-SHA256 of <timestamp>.<raw body>, in signature_header, with Unix seconds in timestamp_header, which is required. The timestamp must be within five minutes.
• verify: github. GitHub's X-Hub-Signature-256, the HMAC-SHA256 of the raw body. GitHub's X-GitHub-Delivery identifies repeats.

An event is identified by its event_key template when the declaration has one, then by a delivery id header, then by a hash of the body. Query parameters are never credentials. The names whatsapp, telegram and the Hub's WEBHOOK_INBOUND_NAME are refused, because the inbound receiver already serves them. See the workflow API and webhooks.

Next stepsCopy Anchor Link