Call a Bot URL
Section titled “Call a Bot URL”This page is for the person or app that received a Bot URL and a key from its owner. You need two things:
- the URL, such as
https://amber-falcon-river-k7m2q.hoody.bot - a key, a secret that starts with
hbk_
You need no Hoody account. To talk to the Bot from a browser, open the URL: see The chat page.
Replace https://amber-falcon-river-k7m2q.hoody.bot in the examples with your own Bot URL. The shell examples read it from BOT, and the key from the HOODY_BOT_KEY environment variable, which the Hoody CLI and the coding-agent setups below read. Paste the key when read waits; it is not shown and stays out of your shell history:
BOT='https://amber-falcon-river-k7m2q.hoody.bot'read -rs HOODY_BOT_KEY && export HOODY_BOT_KEYWhat to paste where
Section titled “What to paste where”| Client | Setting | Value |
|---|---|---|
| OpenAI SDK or any OpenAI-compatible app | Base URL | https://<label>.hoody.bot/v1 |
| Anthropic SDK | Base URL | https://<label>.hoody.bot |
| MCP client | Server URL | https://<label>.hoody.bot/mcp |
| All of them | API key | your hbk_… key |
The model list has one model, and its id is the label. Send it as model, or any other name: the Bot answers either way.
Where the key goes
Section titled “Where the key goes”Send the key in exactly one of these places:
Authorization: Bearer hbk_…, which the OpenAI SDK and most apps usex-api-key: hbk_…, which the Anthropic SDK uses?key=hbk_…at the end of the URL, for tools that cannot set headers
Sending the same key twice is fine. Two different keys in one request are refused with key_invalid. Prefer a header: a URL with ?key= ends up in browser history and in the logs of tools along the way.
Test the key
Section titled “Test the key”printf 'Authorization: Bearer %s\n' "$HOODY_BOT_KEY" | curl -sS "$BOT/v1/models" --header @-printf is built into the shell, so the key reaches curl on its input and never shows up in a command line another program on the machine can read.
{ "object": "list", "data": [ { "id": "amber-falcon-river-k7m2q", "object": "model", "created": 1792137600, "owned_by": "hoody" } ]}Send a message
Section titled “Send a message”printf 'Authorization: Bearer %s\n' "$HOODY_BOT_KEY" | curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/chat/completions --header @- \ -H "Content-Type: application/json" \ -d '{ "model": "amber-falcon-river-k7m2q", "messages": [{ "role": "user", "content": "Is the nightly build green?" }] }'import OpenAI from 'openai';
const bot = new OpenAI({ baseURL: 'https://amber-falcon-river-k7m2q.hoody.bot/v1', apiKey: process.env.HOODY_BOT_KEY,});
const reply = await bot.chat.completions.create({ model: 'amber-falcon-river-k7m2q', messages: [{ role: 'user', content: 'Is the nightly build green?' }],});console.log(reply.choices[0].message.content);The Responses API works the same way: bot.responses.create({ model, input }).
import Anthropic from '@anthropic-ai/sdk';
const bot = new Anthropic({ baseURL: 'https://amber-falcon-river-k7m2q.hoody.bot', apiKey: process.env.HOODY_BOT_KEY,});
const reply = await bot.messages.create({ model: 'amber-falcon-river-k7m2q', max_tokens: 1024, messages: [{ role: 'user', content: 'Is the nightly build green?' }],});console.log(reply.content[0].text);from openai import OpenAIimport os
bot = OpenAI( base_url="https://amber-falcon-river-k7m2q.hoody.bot/v1", api_key=os.environ["HOODY_BOT_KEY"],)
reply = bot.chat.completions.create( model="amber-falcon-river-k7m2q", messages=[{"role": "user", "content": "Is the nightly build green?"}],)print(reply.choices[0].message.content)import { BotUrlClient, isBotUrlError } from 'hoody-sdk';
const bot = new BotUrlClient({ url: 'https://amber-falcon-river-k7m2q.hoody.bot', key: process.env.HOODY_BOT_KEY!,});
try { // Streams by default; onText gets each piece as it arrives const reply = await bot.chat('Is the nightly build green?', { onText: (piece) => process.stdout.write(piece), }); console.log('\nrequest id:', reply.requestId);} catch (e) { if (isBotUrlError(e)) console.error(e.code, e.status, e.retryable, e.requestId); else throw e;}What the client retries for you. Cold starts (bot_starting), brief outages and 429 answers whose Retry-After is 30 seconds or less, for about two minutes at most. After that, or when a Retry-After is longer than the time left, it throws a BotUrlError.
Repeating a chat safely. Each chat() call sends its own Idempotency-Key, which its retries reuse, so a retry normally gets the saved answer instead of posting again (best effort; see Long answers). Pass idempotencyKey to set your own, or false to send none.
When to check before you resend. ask() with text, answer() and a chat() without a key are sent again only after a refusal that comes before the Bot acts (rate_limited, concurrency_limit, ip_blocked, bot_starting, bot_unavailable). When such a request may have reached the Bot and its answer was lost, the client throws outcome_unknown: read getStatus() or listUpdates() before you send it yourself.
Streams. An error inside a streamed answer is thrown at once as a BotUrlError with its retryable flag, and the client does not retry it: you decide whether to call again. For a streamed chat() without a key, outcome_unknown applies only before the first text arrives. Once text has arrived, a stream that breaks off is thrown as stream_interrupted, and an error sent inside the stream keeps its own code. Both may mean the Bot has already acted.
ask(), listUpdates(), answer() and getStatus() use the MCP tools; ask() keeps waiting while the answer is working.
# The key is read from HOODY_BOT_KEY; there is no --key flaghoody boturls ask https://amber-falcon-river-k7m2q.hoody.bot \ "Is the nightly build green?"
# Stream the reply insteadhoody boturls chat https://amber-falcon-river-k7m2q.hoody.bot \ "Is the nightly build green?"hoody boturls models list, status, updates list and answer take the URL the same way. See The Hoody CLI for installing, waiting, JSON output and exit codes.
Your own answer names its rows in the Bot’s shared log. message_seq is the seq of the row your message wrote; reply_seq is the seq of the last row of its reply, where a spoken reply’s audio belongs. Chat completions, Responses responses and Anthropic messages carry them in a top-level hoody object. MCP ask, answer and ask_audio carry them in structuredContent.
In a streamed answer, hoody appears on the chat completion chunk that carries the answer, on the response in response.completed, or on the Anthropic message_delta event. Each field is left out while unknown or when there is no such row; a reply still working or cut by a reset can have message_seq without reply_seq. Rejoining or replaying the same message returns the same known values.
These values name rows; they are not cursors. Keep using the resume position returned by updates or the event stream to read on. The values match the seqs those rows show, but only your own answer carries this correlation: updates and /events do not.
How the Bot reads a request
Section titled “How the Bot reads a request”A Bot is not a stateless model. It keeps its own conversation, so only the last message of your request is posted to it, not counting the instruction messages described below. Earlier messages and sampling settings are ignored. The last message must be the user’s, and text of at most 64 KiB (65,536 bytes of UTF-8, not characters); an image, audio or file part is refused with invalid_request.
The Bot never runs your tools. Tool definitions you send are ignored, except that a tool_choice forcing a tool is refused with 400 invalid_request.
Instructions and client notes stay private
Section titled “Instructions and client notes stay private”Apps and coding agents send instructions along with your message. They are never posted, so other key holders cannot read them, and the Bot does not see them either: it follows its owner’s setup. Only a side request passes them on, to the model that answers it.
- System messages are instructions wherever they sit in the request. On
/v1/messagesthat means thesystemfield andsystemmessages. On/v1/chat/completionsand/v1/responses, developer messages count too, and so does the Responsesinstructionsfield. - Client notes count too: a text block of the last user message that holds only a note from
<system-reminder>to</system-reminder>. Claude Code sends yourCLAUDE.mdfiles and environment notes this way. - Whole blocks only. A note with other text before or after it in the same block is posted whole, note included. Text between two notes in one block goes with the block and is not posted. Send each note as its own block.
- A request that holds only instructions, or whose last message holds only notes, is refused with
400 invalid_request.
Side requests
Section titled “Side requests”Apps also send small tasks of their own, such as “write a title for this chat”. On the three chat doors, a request is a side request when it sends no tools and either:
- asks for 64 output tokens or fewer, in the door’s output budget field (see the table below), or
- carries a known chat-app task prompt: the title, tags and follow-up questions of apps such as Open WebUI and LibreChat, or Claude Code’s session title (an
output_configasking for a JSON object whose one property istitle, with Claude Code’s<session>prompt and its fixed closing sentence as the last user message).
| Door | Output budget field |
|---|---|
/v1/chat/completions | max_completion_tokens, or max_tokens when it is absent. Both must be positive when sent. |
/v1/responses | max_output_tokens |
/v1/messages | max_tokens |
A budget below 1 is refused with invalid_request. A field the door does not read, such as max_tokens on /v1/responses, does not make a side request.
The Bot’s model answers a side request outside the Bot: nothing is posted to the conversation or shown in its log. The answer is capped at your token limit or 1024 tokens, whichever is lower. When the model cannot take that cap, the answer is 502 upstream_error. Side requests count toward the request limits and appear in the owner’s access log.
A request with tools is never a side request, on every door; an empty tools list counts as none. For a real message, send a larger token limit or none, and do not paste a chat app’s task prompt. MCP ask is never a side request.
Use it from a coding agent
Section titled “Use it from a coding agent”A coding agent can use the Bot as its model. The Bot does not run the agent’s tools: it answers in text, and the agent takes that as its answer. Each setup below reads the key from HOODY_BOT_KEY, never from a file or a command line.
Tested with Claude Code 2.1.302. The base URL has no /v1, and any model name works:
export ANTHROPIC_BASE_URL='https://amber-falcon-river-k7m2q.hoody.bot'export ANTHROPIC_API_KEY="$HOODY_BOT_KEY"claude -p --bare --model claude-sonnet-4-5 'Reply with exactly: pong'--bare sends only your prompt, without your CLAUDE.md files and environment notes, and it needs ANTHROPIC_API_KEY (ANTHROPIC_AUTH_TOKEN does not work with it). For interactive use, set these too and run claude; on the first start, answer Yes to using the detected API key:
export ANTHROPIC_MODEL=claude-sonnet-4-5 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=falseclaudeWithout --bare, Claude Code sends your CLAUDE.md files and environment notes as instructions, which stay private (see Instructions and client notes). Your prompts are posted and other key holders can read them.
Tested with Codex CLI 0.163.0. Create ~/.codex/bot.config.toml; your config.toml stays as it is:
model = "bot"model_provider = "hoody"
[model_providers.hoody]name = "Hoody Bot"base_url = "https://amber-falcon-river-k7m2q.hoody.bot/v1"env_key = "HOODY_BOT_KEY"wire_api = "responses"codex exec --profile bot --skip-git-repo-check 'Reply with exactly: pong'The profile name is the file name: if you already have a bot.config.toml, pick another name. A “Model metadata for bot not found” warning is harmless.
Tested with opencode 1.19.3. In ~/.config/opencode/opencode.json or ./opencode.json; baseURL ends in /v1, and the model must be listed under models:
{ "$schema": "https://opencode.ai/config.json", "provider": { "hoody": { "npm": "@ai-sdk/openai-compatible", "name": "Hoody Bot", "options": { "baseURL": "https://amber-falcon-river-k7m2q.hoody.bot/v1", "apiKey": "{env:HOODY_BOT_KEY}" }, "models": { "bot": { "name": "Hoody Bot" } } } }, "model": "hoody/bot"}opencode run 'Reply with exactly: pong'opencode’s built-in anthropic provider works too, with the same baseURL and apiKey and the model anthropic/claude-sonnet-4-5.
Tested with pi 1.3.0 (npm install -g @earendil-works/pi-coding-agent). In ~/.pi/agent/models.json (in an existing file, add hoody under providers). pi reads $HOODY_BOT_KEY from the environment when it calls, so the key never goes in the file:
{ "providers": { "hoody": { "baseUrl": "https://amber-falcon-river-k7m2q.hoody.bot/v1", "api": "openai-completions", "apiKey": "$HOODY_BOT_KEY", "models": [{ "id": "bot" }] } }}pi -p --model hoody/bot 'Reply with exactly: pong'"api": "openai-responses" works too with the same baseUrl, and "anthropic-messages" with the baseUrl https://amber-falcon-river-k7m2q.hoody.bot (no /v1).
The Hoody CLI
Section titled “The Hoody CLI”The CLI needs Node.js 20.19 or later and no Hoody account:
npm install -g hoody-sdk@1.0.1hoody boturls models list "$BOT"hoody boturls ask "$BOT" "Summarize the open work"To skip the install, put npx -y hoody-sdk@1.0.1 in place of hoody.
- The key. The CLI reads it from
HOODY_BOT_KEY, from the variable--key-envnames, or from the file--key-file <path>names (-reads standard input). There is no--keyflag, so the key never lands in your shell history or in a process list, and the CLI never prints it. - Waiting.
askfollows aworkinganswer with a polling budget of 10 minutes.--max-wait <seconds>changes the budget, and--no-waitreturns the first answer. The budget is checked between requests, so a request already in flight can finish after it. Whenaskstill ends withworking,hoody boturls ask "$BOT" --ref '<ref>'waits for the same reply and sends nothing new. - JSON.
-o jsonprints the result as JSON (askandanswer:status,text,ref,requestId). A failed call with an error code prints{"error":{"code":…,"message":…,"status":…,"request_id":…}}on standard output, and every failure also prints a line on standard error. With-o json, setup failures such as a missing key also print an error object on standard output, usingusage_error, status0andrequest_id: null; a diagnostic also goes to standard error. - Exit codes.
0for a result,1for a failed call,2for a setup or usage error.askalso exits0when the status isworkingorwaiting_on_gate, so readstatus.
| Command | What it does |
|---|---|
models list | Checks the key: lists one model. |
ask | Sends a message and waits for the reply. |
chat | Sends a message through the chat door and streams the reply. |
updates list [--cursor <cursor>] | Reads what the Bot logged. The next cursor comes last, on standard error (with -o json, in cursor). |
status | Whether a turn is running, and the pending approvals of the Bot’s agents. |
events stream [--cursor <cursor>] [--max-wait <seconds>] | Follows the Bot’s live events. With -o ndjson or -o json, one JSON line per event; human terminal output uses formatted event lines. |
answer --gate-id <gate_id> --decision <decision> [--text <text>] | Answers a pending approval: approve, allow_session, deny or answer. |
The CLI and the SDK accept hoody.bot addresses. For a Bot under another domain, add --zone (SDK option zone) with the host name minus its first label.
The MCP server at /mcp gives an agent six tools:
| Tool | What it does |
|---|---|
ask | Send the Bot a message and wait about 50 seconds for its reply. |
updates | Read what the Bot logged after a cursor: messages, replies, reports from its agents, approval questions. |
answer | Answer an approval or a question one of the Bot’s agents is waiting on. |
status | Whether the Bot is working, which approvals wait, and whether it can listen and speak. |
speak | Turn text into speech. Not a message to the Bot. |
ask_audio | Send the Bot a spoken message and get the reply as text and audio. |
Add the server to .mcp.json in your project. Claude Code fills in ${HOODY_BOT_KEY} from the environment when it starts, so the key stays out of the file and off the command line:
{ "mcpServers": { "my-bot": { "type": "http", "url": "https://amber-falcon-river-k7m2q.hoody.bot/mcp", "headers": { "Authorization": "Bearer ${HOODY_BOT_KEY}" } } }}A project .mcp.json needs your approval once: run claude in the project and approve the server. Until then, claude mcp list shows it as pending approval. If HOODY_BOT_KEY is not set when Claude Code starts, it warns about the missing variable by name, and the Bot answers 401 key_invalid.
Most MCP clients accept this shape. The file then holds your key: keep it private and out of version control.
{ "mcpServers": { "my-bot": { "type": "http", "url": "https://amber-falcon-river-k7m2q.hoody.bot/mcp", "headers": { "Authorization": "Bearer hbk_…" } } }}printf 'Authorization: Bearer %s\n' "$HOODY_BOT_KEY" | curl -sS https://amber-falcon-river-k7m2q.hoody.bot/mcp --header @- \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"ask","arguments":{"text":"Is the nightly build green?"}}}'The server keeps no session: POST each request. It offers no ongoing subscription to what the Bot does: subscriptions/listen answers with a short event stream, an acknowledgement with an empty notification filter followed by the result, and closes, and a GET that asks for an event stream answers 405. To follow the Bot as it works, use its live events. Send one JSON-RPC message per request; a batch (a JSON array of messages) is refused with 400 invalid_request and none of it runs. A DELETE of /mcp answers 405.
Approvals show up with a handle such as g_Q2xV8nT0aLr3Yk1Ww5mZpA instead of an internal id. Pass that handle to answer. A handle stops working once the approval is decided or replaced; read status for the current ones.
When something waits for you, the results of ask, ask_audio, answer and status end with one line such as 2 new messages and 1 approval waiting: call updates., and status carries the same counts as pending. The Bot’s owner can turn the line off with the Bot’s mcp_hints setting. In the Hub, open Bots, select the Bot, open Bot settings → Behaviour, turn off Tell connected apps what is waiting, and choose Save. The counts in status stay.
New messages are the Bot’s replies and notices that you, with your key, have not been shown yet; a waiting approval counts as an approval. Each key keeps its own place:
- An answer, on any door, is built from the rows the Bot logged since the previous answer to any caller. When it reaches you in full, it marks those rows and its own reply as seen, but only if they start at or before the first row you have not seen. When another caller’s answer already took rows you were not shown, your answer marks nothing: those rows, and your answer’s own reply, keep counting until an
updatesread from your cursor shows them. An answer that did not arrive in full marks nothing. - Rows an answer leaves out to fit its size count as seen. A public answer leaves them out without a note. They stay in the log, and
updatesfrom an earlier cursor returns them. - An
updatesread marks its rows as seen when it starts at or before the first row you have not seen. A read from a later cursor, or one without a cursor (the newest 20 rows) while more rows wait, leaves the earlier rows counted: page on from your cursor to clear them. - Rows your event stream delivers count as seen under the same rule as
updates, each once it was sent in full. The stream goes on from theLast-Event-IDyou sent. A stream opened without one (it starts with the newest 20 rows), and the rows after agaporarchivedevent, start past rows you never got, so they leave the earlier rows counted. Itsstatusevents carry the samepending. - Another caller’s answers never clear your count.
The count is approximate: read messages as about that many new messages, and call updates for the rows themselves. It looks at most 500 rows back. When it stops there, the line names only what it saw, such as At least 3 new messages and 1 approval waiting: call updates., or New messages may be waiting: call updates. when it saw none, and pending ({messages, approvals}) has more: true: messages is then a lower bound. When the log cannot be read, messages is left out.
The Bot can drop a key’s place. A key without one (new, dropped while many keys call the Bot, or after the Bot’s agent restarted) counts from the Bot’s shared position, which every caller’s answers move, until its first answer or updates read sets its place, so it can miss rows another caller was shown. When every row matters, read updates with your own cursor.
Listen for events
Section titled “Listen for events”To follow what the Bot does, for example when it starts agents, when they report, or when one waits for an approval, open its live events, or read the Bot’s log and status with these MCP tools. The SDK has the tools as listUpdates(), getStatus() and answer(), and the CLI as hoody boturls updates list, status and answer; both follow the live events too, with streamEvents() and hoody boturls events stream.
The reply stream of a chat door ("stream": true on /v1/chat/completions, /v1/responses or /v1/messages) is not a subscription. It carries the reply to the message that opened it and ends with that reply. The reply can include what the Bot logged since the last answer, such as an approval or a report, including ones that arrived while it waited (When answers wait), but the stream never delivers other callers’ messages or later events.
| Tool | What you get |
|---|---|
updates | The log after a cursor, oldest first, up to 50 rows per call: callers’ messages, the Bot’s replies, reports from its agents, approval questions and notices. Each row has seq, at, role, text, and from for messages from callers. Without a cursor you get the newest 20 rows. Pass the returned cursor next time; has_more is true when more rows wait. |
status | Whether the Bot is on a turn (turn_running), how many messages are queued, its autonomy budget, whether it waits for its owner, voice (see below), pending (see MCP), caller ({"key_name": …}: the name of your key, the same name your messages carry in from as key:<name>), and open_delegates: the agents it started, each with its title, working, last_report_at and pending_gates (gate_id, type, summary). An agent stays open after it reports, so working: false with a last_report_at means it finished. Right after the Bot’s agent restarts, working can be false with state_unknown: true until the Bot is back in touch with that agent. |
answer | Decides one pending approval by its gate_id: approve, allow_session, deny (with text: why, up to 500 characters) or answer (with text: the answer to a question). It reaches the Bot as your message, the Bot applies it, and you get the Bot’s reply as with ask. |
Live events
Section titled “Live events”GET /events on the Bot URL sends the same rows as updates and the same object as status, as Server-Sent Events, while they happen. Send your key as on any other path and send no body:
printf 'Authorization: Bearer %s\n' "$HOODY_BOT_KEY" | curl -sSN "$BOT/events" --header @-retry: 1000
event: statusdata: {"address":"https://amber-falcon-river-k7m2q.hoody.bot","autonomy":…,"turn_running":false,"voice":…}
event: rowid: 41data: {"seq":41,"at":"2026-10-18T13:40:02Z","role":"user","from":"key:ci","text":"Run the full test suite and tell me what fails."}
event: rowid: 42data: {"seq":42,"at":"2026-10-18T13:40:09Z","role":"bot","text":"Started an agent on the test suite. I will report when it is done."}
:
event: enddata: {"reason":"reconnect"}The status line above is shortened. The stream sends these events:
| Event | id: | data | When |
|---|---|---|---|
status | none | The object the status tool returns | First, then each time it changes. |
row | the row’s seq | One row, as updates returns it | For each row, oldest first. Rows that updates leaves out are left out here too. |
cursor | the new position | {"seq":n} | At the end of the catch-up when you connected without Last-Event-ID, where the new rows begin; when rows that are left out moved your position past the last row; or when there was nothing to show. On an empty log the id is 0. |
gap | next_seq − 1 | {"next_seq":n} | The log no longer holds the rows after your position, or your position is ahead of the log. Some rows were missed; the stream goes on from next_seq. |
archived | next_seq − 1 | {"next_seq":n} | The log was archived while you listened: the rows you saw are no longer in it. The stream goes on from next_seq. |
end | none | {"reason":"reconnect"} | Shortly before the stream’s time is up, or when the Bot restarts. Connect again. |
error | none | {"code":…,"message":…} | Something failed after the stream started: bot_disabled, upstream_error or internal_error. The stream closes. |
A line with only : is a heartbeat, sent every 15 seconds. The stream carries finished rows only: not the reply while it is written, nor the Bot’s thinking or tool calls. turn_running in status shows that the Bot is working.
Reconnect. A stream lasts at most 25 seconds, then sends end and closes. Connect again after the retry delay (1 second), with the Last-Event-ID header set to the last id: you received, from any event that has one. Keep that id, not the seq of the last row you showed: cursor, gap and archived move it too, and gap and archived can move it back.
Last-Event-ID | The stream starts with |
|---|---|
| left out or blank | the 20 newest rows, as updates without a cursor |
0 | every row the log still holds |
| a number | the rows after it. Decimal digits only (spaces around them are ignored), at most 16 of them, up to 9007199254740991; anything else, or the header sent twice, is refused with 400 invalid_request |
The position goes in the header only; a query string is not passed on to the Bot.
Limits. Each connection counts as one request toward the per-minute limits, so one listener costs 2 to 3 requests a minute. An open stream does not hold one of your call slots. Streams have their own caps instead: 4 open at once per key, 32 per Bot and 16 per IPv4 address. Another one is refused with 429 concurrency_limit and Retry-After: 1.
When there are no events. A Bot whose agent is older answers /events with 404 path_not_allowed. Treat path_not_allowed and method_not_allowed there as “no live events” and poll instead.
import { BotUrlClient } from 'hoody-sdk';
const bot = new BotUrlClient({ url: 'https://amber-falcon-river-k7m2q.hoody.bot', key: process.env.HOODY_BOT_KEY!,});
const events = bot.streamEvents(); // or bot.streamEvents({ cursor, signal })for await (const e of events) { if (e.type === 'row') console.log(e.row.seq, e.row.role, e.row.text); if (e.type === 'status') console.log('working:', e.status.turn_running); if (e.type === 'gap' || e.type === 'archived') console.log(`(${e.type}: earlier rows are gone)`);}streamEvents() yields status, row, gap and archived events and reconnects by itself. events.getCursor() is the position to go on from later: pass it as cursor. An AbortSignal in signal, or break, stops it. Where the Bot URL has no event stream yet, it polls status every 15 seconds and updates when the status changed (events.getMode() turns 'poll'); fallback: 'none' throws instead.
hoody boturls events stream "$BOT"# Go on from the cursor a previous run printed, with no time limithoody boturls events stream "$BOT" --cursor '<cursor>' --max-wait 0Use hoody boturls events stream "$BOT" -o ndjson for one JSON line per event. Human terminal output uses formatted event lines. The CLI prints events until --max-wait (default 600 seconds, 0 for no limit) or Ctrl-C, then, when a position is known, the cursor to go on from, as cursor: <n> on standard error. Where the Bot URL has no event stream yet, it says so on standard error and polls instead.
const BOT = 'https://amber-falcon-river-k7m2q.hoody.bot';const KEY = process.env.HOODY_BOT_KEY!;const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
let lastId: string | undefined; // the resume positionlet fails = 0; // cold-start retries in a rowfor (;;) { const headers: Record<string, string> = { Authorization: `Bearer ${KEY}` }; if (lastId !== undefined) headers['Last-Event-ID'] = lastId; const res = await fetch(`${BOT}/events`, { headers }); if (res.status !== 200) { const code = res.headers.get('X-Hoody-Error-Code'); if (code === 'PATH_NOT_ALLOWED' || code === 'METHOD_NOT_ALLOWED') break; // poll instead if (code === 'BOT_UPGRADE_REQUIRED') throw new Error("ask the Bot's owner to update the agent"); if (res.status === 429) { // rate_limited, concurrency_limit, ip_blocked await sleep(Number(res.headers.get('Retry-After') ?? 5) * 1000); continue; } if ((code === 'BOT_STARTING' || code === 'BOT_UNAVAILABLE') && fails < 8) { await sleep(Math.min(30_000, 1000 * 2 ** fails++)); // 1 s, 2 s, 4 s … 30 s: no Retry-After continue; } throw new Error(`${res.status} ${code}`); } fails = 0; const decoder = new TextDecoder(); let buf = '', event = '', id: string | undefined, data = ''; for await (const chunk of res.body!) { buf += decoder.decode(chunk, { stream: true }); for (let nl; (nl = buf.indexOf('\n')) >= 0; ) { const line = buf.slice(0, nl).replace(/\r$/, ''); buf = buf.slice(nl + 1); if (line.startsWith('event: ')) event = line.slice(7); else if (line.startsWith('id: ')) id = line.slice(4); else if (line.startsWith('data: ')) data += line.slice(6); else if (line === '') { // a blank line ends an event if (id !== undefined) lastId = id; if (event === 'row') { const r = JSON.parse(data); console.log(r.seq, r.role, r.text); } if (event === 'gap' || event === 'archived') console.log(`(${event}: earlier rows are gone)`); if (event === 'error') throw new Error(JSON.parse(data).code); // bot_disabled, upstream_error, internal_error event = data = ''; id = undefined; } } } await sleep(1000); // after end, or a closed connection}The loop waits out a 429 for its Retry-After, and retries a cold start (bot_starting) or a brief outage (bot_unavailable) after 1 second, then longer, up to 30 seconds apart, for about two minutes. It stops on anything else. bot_upgrade_required is a 503 too, but retrying does not help: only the Bot’s owner can fix it, by updating the agent.
// EventSource cannot send headers, so the key goes in the address.// Use this only where you cannot send the header, and only when the URL allows browser access.const es = new EventSource( 'https://amber-falcon-river-k7m2q.hoody.bot/events?key=' + encodeURIComponent(key));es.addEventListener('status', e => showStatus(JSON.parse(e.data)));es.addEventListener('row', e => showRow(JSON.parse(e.data)));es.addEventListener('archived', () => markOlderRowsGone());es.addEventListener('error', e => { if (e instanceof MessageEvent) console.warn('stream error', JSON.parse(e.data).code);});An EventSource reconnects after end by itself and sends Last-Event-ID for you. When a connection is refused (any answer other than 200), it stops for good: fetch /events once to read the error code.
The SDK and the CLI reconnect with no attempt or time limit. After rate_limited, the wait grows from 30 seconds to 2 minutes, and resets after 5 minutes without one. An error that retrying cannot fix, such as key_invalid or bot_disabled, ends the stream, and so does a 429 whose Retry-After is over 30 seconds (SDK option retry.maxDelayMs; the CLI always uses 30 seconds). The CLI still stops at --max-wait.
Poll the log
Section titled “Poll the log”A loop that prints the log as it grows and shows pending approvals:
import { BotUrlClient } from 'hoody-sdk';
const bot = new BotUrlClient({ url: 'https://amber-falcon-river-k7m2q.hoody.bot', key: process.env.HOODY_BOT_KEY!,});const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
let cursor: number | undefined;for (;;) { const page = await bot.listUpdates(cursor); for (const row of page.items) console.log(row.seq, row.role, row.text); cursor = page.cursor; if (page.hasMore) continue; // read the rest at once
const s = await bot.getStatus(); for (const d of s.open_delegates ?? []) for (const g of d.pending_gates ?? []) console.log('waiting:', d.title, g.gate_id, g.summary);
await sleep(30_000); // 4 requests a minute while idle}# The first call prints the newest rows; the cursor is the last line on standard errorhoody boturls updates list "$BOT"# Then read only what is newhoody boturls updates list "$BOT" --cursor '<cursor>'# Pending approvals of the Bot's agents, with their gate_idhoody boturls status "$BOT"hoody boturls answer "$BOT" --gate-id '<gate_id>' --decision approveEvery poll is a request and counts toward the limits: by default 60 a minute for your key, and 120 a minute for the whole Bot, shared with every other caller. Poll every 15 to 30 seconds while you wait, and less often when nothing is happening. Reading updates does not change what ask returns.
Voice and approvals in status
Section titled “Voice and approvals in status”status.voice holds two booleans. They say whether a speech model is available for each direction, including the default Hoody AI voices; they do not check whether the provider answers right now. Check them before you use voice:
listen: false:ask_audiocannot take speech. It fails withupstream_error, and retrying does not help.speak: false:speakfails withupstream_error, andask_audiostill answers, in text without audio.
When ask_audio returns status: "answered" without audio, do not send the message again just to get audio. A no_speech result means nothing was sent to the Bot.
Answer an approval with its gate_id, never just with the agent’s title: a title goes to whichever approval holds it at that moment, which can be a newer one. A handle that has closed is refused with request_not_found; read status again.
Streaming and keepalives
Section titled “Streaming and keepalives”Set "stream": true on /v1/chat/completions, /v1/responses or /v1/messages to get the reply as Server-Sent Events. The reply arrives whole, in one piece, once the Bot has finished; there is no word-by-word typing. Until then the stream carries a keepalive about every 15 seconds, so proxies and load balancers along the way do not close it:
- Before the Bot has taken the message, every door sends a comment line,
: keepalive. - Once the answer has started, the OpenAI doors keep sending
: keepaliveand the Anthropic door sendsevent: ping.
A streamed request waits up to 10 minutes for the reply. A non-streamed one waits up to 100 seconds, which stays under the 120-second limit many clients and proxies use.
printf 'Authorization: Bearer %s\n' "$HOODY_BOT_KEY" | curl -sS -N https://amber-falcon-river-k7m2q.hoody.bot/v1/chat/completions --header @- \ -H "Content-Type: application/json" \ -d '{"model":"amber-falcon-river-k7m2q","stream":true, "messages":[{"role":"user","content":"Run the full test suite and tell me what fails."}]}'If the stream fails after it started, it ends with the door’s own error frame carrying the error code.
Long answers
Section titled “Long answers”Some work takes the Bot longer than one request can wait, so you ask, then fetch the answer later. Nothing is lost when that happens: the message stays posted and the Bot keeps working.
- OpenAI and Anthropic doors. When the wait runs out, the reply says the Bot is still working. Send the same request again later. Because you got that reply, the Bot does not receive your message twice: the repeat waits for the same reply, and returns it once it is ready. The reply may start with what the Bot logged since your last answer.
- MCP.
askreturnsstatus: "working"and aref. Callaskagain with thatrefand notextto keep waiting. Useupdateswith a cursor to follow progress in between.asktakes no idempotency key: the same text sent again while the earlier ask is still unanswered shares its reply, but once that reply was delivered, the same text is a new message. A message the Bot finished that nobody was told about is also sent as new after 2 minutes. To rejoin an earlier ask, pass itsref.
To make repeats safe after a lost connection, send an Idempotency-Key header with a new unique value for every new message, and repeat it unchanged. Before repeating anything that changes things, check with status or updates, or poll the ref you got back.
A repeat with the same key and content normally joins the running message or returns its saved answer instead of posting again. This is best effort, not a guarantee:
- How long. The Bot keeps key records for about 24 hours after the message was accepted, sometimes a little longer. Once the record is gone, the repeat is a new message. A Bot holding very many recent keys refuses a new key instead of forgetting an old one.
- Saved answers can be dropped earlier when many are stored. That alone does not make a keyed retry a new message: while its key record remains, the retry rejoins the earlier message and reads its answer from the log.
- Resets. A reset that replaces the message’s session when no saved answer remains can make the retry a new message even while its key record remains. A message still queued at the reset continues in the new session.
- Scope. Keys are per API key: another caller using the same value does not collide with you. Reusing a key with different content is refused with
request_conflict.
Without an Idempotency-Key, a repeat of the same messages rejoins the earlier message while the Bot is still working on it. An undelivered saved answer is replayed while it is less than 2 minutes old; a delivered or older answer makes the repeat a new message. If the Bot finished without saving an answer and you never received the “still working” reply, a repeat rejoins until 2 minutes after the message was accepted, then posts again. Send an explicit key whenever a duplicate message would matter.
ask status | Meaning |
|---|---|
answered | text holds the reply. |
working | Still working. Call ask with ref. |
waiting_on_gate | The Bot itself waits for an approval or a question that only its owner can answer, in the Hub (Bots) or the terminal app. answer cannot resolve it. Send a new message, which skips it. |
reset | The Bot was reset before it answered. Send the message again. |
dropped | The message was not delivered; text explains why. Polling its ref returns dropped again. Repeating the same text within two minutes of the first request also returns dropped; after that, it sends a new message. |
When answers wait
Section titled “When answers wait”When the Bot’s reply hands work to its agents, the answer can wait a few seconds more, so that an approval the work needs right away arrives in the same answer. A chat app has no other way to show it before your next message. The Bot’s owner chooses how this works with two settings on the Bot:
| Setting | Default | What it does |
|---|---|---|
async | false | false: the answer waits for every agent the reply started to take its first step. An agent has taken it once it asks for an approval or an answer, reports, stops, or finishes its first tool call without asking. true: the answer comes as soon as the Bot’s reply is written. |
wait_seconds | 15 | The longest that wait lasts, from 1 to 60 seconds. It is not used while async is true. |
When an agent asks for an approval during the wait, the answer ends with what the Bot said about it; reply in the chat to answer, or use answer over MCP. A reply that starts no new agent never waits, even when it sends an agent that is already open a message. The wait also ends with the request’s own limit, so it lasts at most what is left of that limit: on the OpenAI and Anthropic endpoints 100 seconds, or 10 minutes when streamed; over MCP, ask and answer wait about 50 seconds in all; ask_audio also needs time for transcription before its reply wait and audio generation afterward (see Long answers). Whatever the agents ask or report after the answer reaches you with the answer to your next message, and through updates over MCP.
The wait looks only at each agent’s first step. When that step is a tool call that needs no approval, such as reading a file, the answer ends once it finishes, even if the agent’s next call asks for an approval; the same holds when an agent runs several calls at once and one finishes before another asks. That approval then comes with your next message, through updates, or in the Bot’s live events.
The setting is the same for every caller and every door: the OpenAI and Anthropic endpoints and the MCP tools ask, answer and ask_audio. Which value fits depends on how the Bot is called:
- Apps that only see the Bot’s answers, such as OpenCode, a chat app, or your own code calling the OpenAI or Anthropic API: keep
asyncset tofalse. These apps show nothing between two answers, so an approval asked in the first seconds is worth the short wait. Raisewait_secondswhen the Bot’s agents usually need longer before they ask. - Clients that follow the Bot on their own, such as a web page or a program that keeps reading the Bot’s live events or polls
updates: setasynctotrue. They see approvals as they come, so a quick answer serves them better.
The owner changes the settings with PATCH /api/v1/agent/bots/{id} on the agent (Agent: Bots). The next answer uses the new values; the Bot does not need a reset.
Every path
Section titled “Every path”| Method | Path | Key | What it does |
|---|---|---|---|
GET | / | No | The text manual. A browser gets the chat page instead. |
GET | /SKILL.md | No | The same instructions as a Skill an AI agent can load. |
OPTIONS | any path below | No | Browser preflight. Refused with cors_disabled when the owner turned browser access off. |
GET | /v1 | Yes | A short text page on how to use the Bot from an OpenAI client. |
GET | /v1/models | Yes | The model list: one model, whose id is the label. |
GET | /v1/models/<model> | Yes | The label’s model, for a name of 1 to 128 ASCII letters, digits, dots, underscores, colons or hyphens, except . and ... Other names return 404 path_not_allowed. |
GET | /v1/key | Yes | Returns {object: "bot.key", name, holder_note} for this key, without waking the computer; holder_note is null when absent. |
POST | /v1/chat/completions | Yes | OpenAI Chat Completions. |
POST | /v1/responses | Yes | OpenAI Responses. |
POST | /v1/messages | Yes | Anthropic Messages. |
POST | /mcp | Yes | The MCP server: one JSON-RPC message per request. |
GET | /mcp | Yes | A short text page on how to use the MCP server. Asking it for an event stream gets 405. |
DELETE | /mcp | Yes | Always 405: the server keeps no session. |
GET | /events | Yes | The Bot’s live events: its log rows and status as Server-Sent Events. No body. |
Any other path answers 404 path_not_allowed, and a listed path with another method answers 405 method_not_allowed with an Allow header. Paths are matched exactly.
The keyless manual
Section titled “The keyless manual”Two addresses work without a key and never wake the Bot:
GET https://<label>.hoody.bot/returns a short plain-text manual. Opened in a browser, it shows the chat page instead; add?view=textto see the manual there.GET https://<label>.hoody.bot/SKILL.mdreturns the same instructions as a Skill an AI agent can load.
Both are generic. They name no Bot and say nothing about its owner. To let an AI agent use a Bot, point it at /SKILL.md and give it the key separately.
Request ids
Section titled “Request ids”Every answer carries an X-Request-Id header with 32 hex characters. The Bot’s owner sees the same id in their access log. Quote it when you report a problem. A request id you send yourself is replaced.
What’s Next
Section titled “What’s Next”- Errors and limits: every error code and what to do.
- Security: what your key allows.