Hub Protocol flow

The Hub Protocol is the pod's HTTP API, served under /api/hub. Agents, scripts and integrations in any language use it to read and change what is in a pod. This page follows one request from the caller to the pod's records; the Hub REST API reference lists every route.

The path of a requestCopy Anchor Link

1. The caller authenticates. A script or agent sends an API key as Authorization: Bearer <api-key>. A web client signed in to the pod can send its session token as X-Session-Token instead.
2. The pod works out who is calling. A key held by an agent acts as that agent, on behalf of the person it works for. Any other key acts as the person who owns it.
3. The key's limits are checked. Most routes check hub-protocol.read to read and hub-protocol.write to write; a few pod-setup routes require another scope, such as hub-protocol.admin. If the key has a grant, the request must stay inside it.
4. A read returns only the records the caller is allowed to see (see Permission model).
5. A write is governed. The pod checks the caller's permission, then, for an agent, the validation policy. The write runs, becomes a proposal, or is refused. A proposal is a success: the answer carries status: "proposed" and a proposalId.
6. A change that runs is recorded in the pod's event log, and its follow-up work runs from there: search indexing, automations and webhooks.

Because every step runs on the pod, an agent's write over the Hub REST API is checked and recorded the same way as a person's change in the apps.

What it coversCopy Anchor Link

Records (entities, relations, documents, views), conversations (channels and threads), memory and knowledge, sessions and playbooks, proposals, automations, capabilities and tools, connectors and webhooks, and pod setup. Each pod publishes its exact routes at /api/hub/openapi.json.

See also:

• Hub REST API
• API keys