OpenAI-compatible API

Every Hub answers in the OpenAI chat completions format at /v1, so OpenAI's own clients and any tool that speaks that format can ask the agent. The agent runs with a real person's access, tools and knowledge, exactly as in the chat.

By the end of this page you will have asked the agent from a script and read its answer. There are two ways in:

For people, use the web chat, Slack or WhatsApp and Telegram. For an assistant such as Claude Code, use MCP. For scheduled work, a code workflow calls the agent with hub.call_agent and needs no key. To put the chat inside your own web app, see Chat inside your own app.

What you needCopy Anchor Link

• A deployment with sign-in on, and an account that holds Use this agent. See Authentication.
• Python with the openai package, or curl.

hubzoid auth keys create "Nightly summary" --preset chat --server https://hub.example.com

export HUBZOID_KEY=hzp_...
curl -s https://hub.example.com/v1/models -H "Authorization: Bearer $HUBZOID_KEY"

import os

from openai import OpenAI

client = OpenAI(base_url="https://hub.example.com/v1", api_key=os.environ["HUBZOID_KEY"])
reply = client.chat.completions.create(
    model="my-hub",
    messages=[{"role": "user", "content": "When is support open?"}],
)
print(reply.choices[0].message.content)

What a personal key can doCopy Anchor Link

• A key never does more than its owner can do right now. Blocking or deleting the person, or removing their access, applies to their keys at once.
• A key limited to some agents can only chat, only with those agents, and only through /v1.
• A key never signs in, changes a password or two-step sign-in, creates other keys, or answers an approval. A step that needs an approval waits for the person, and the answer says so.
• A request that carries both a session cookie and a key is refused.

The deployment serves a reference of its public API at /docs, titled Hubzoid API, with the schema at /openapi.json.

On the server: a bridge keyCopy Anchor Link

Each Hub's bridge listens on 127.0.0.1 only, on BRIDGE_PORT, else the first free port from 8000. The public port answers 401 for /v1 without a personal key, and 404 for the bridge's other internal routes (/uploads, /otel).

Requests carry a bridge key as a Bearer token. Keys come from BRIDGE_API_KEYS in the Hub's .env, a comma-separated list. hubzoid init writes a random one into a new Hub's .env.

Who is askingCopy Anchor Link

The bridge key proves the caller may reach the bridge. It does not say who is asking, and the bridge refuses a request without a verified person who holds Use this agent. The person is named in headers:

The headers count only when X-Hubzoid-Assertion covers exactly their values. Python code on the server can sign them the way Hubzoid's own processes do. It needs the deployment key, so run it with the Hub's environment: HUBZOID_SECRET_KEY when set, otherwise <hub>/.hubzoid/secret.key, or the secret.key in the deployment's data folder when several Hubs run together.

from pathlib import Path

import httpx
from hubzoid.assertions import identity_headers

hub = Path("/opt/hubzoid/agents/my-hub")
headers = {
    "Authorization": "Bearer <a key from BRIDGE_API_KEYS>",
    # Sign just before sending: the signature is valid for 60 seconds.
    **identity_headers(hub, surface="api", email="priya@example.com"),
}
reply = httpx.post(
    "http://127.0.0.1:8000/v1/chat/completions",
    headers=headers,
    json={
        "model": "my-hub",
        "chat_id": "nightly-summary",
        "messages": [{"role": "user", "content": "When is support open?"}],
    },
    timeout=300,
)
print(reply.json()["choices"][0]["message"]["content"])

Requests and responsesCopy Anchor Link

A blocking POST /v1/chat/completions answers with one chat.completion object: an id, the model, one entry in choices whose message holds the assistant's content with "finish_reason": "stop", and the token usage. Read the answer from choices[0].message.content, as in the example above.

Set "stream": true to read server-sent events: a first chunk with the assistant role, one chat.completion.chunk per text delta with the same id and created, a chunk with "finish_reason": "stop", a final chunk with empty choices and the token usage, and data: [DONE]. Some chunks carry a status event, such as a tool starting, and no text. OpenAI's clients skip them.

Send the whole conversation each turn. A system message from the caller becomes part of the prompt but does not replace the Hub's own instructions, knowledge or tools. Other OpenAI parameters, such as temperature, tools or response_format, are not applied: the Hub's model settings and tools decide.

Files on the bridgeCopy Anchor Link

Attach a file inline as a base64 data URL. Images use an image_url part. Other files use an input_file or file part with a name:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Compare this count sheet with the system stock." },
    { "type": "input_file", "name": "count-sheet.csv", "data": "data:text/csv;base64,c2t1LGNvdW50ZWQK..." }
  ]
}

Or upload the raw file first, with the bridge key, and refer to it by name in the same chat:

curl -s -X POST http://127.0.0.1:8000/uploads/nightly-summary/count-sheet.csv \
  -H "Authorization: Bearer $HUBZOID_BRIDGE_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @count-sheet.csv

Bridge endpointsCopy Anchor Link

The full list, including the Settings and MCP routes, is in HTTP endpoints.

If something goes wrongCopy Anchor Link

Next stepsCopy Anchor Link