Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

This page covers creating a Bot URL for one of your Bots and managing the keys that open it. You need to own the project the Bot’s computer belongs to. Project collaborators can use the computer, but they cannot create or change its Bot URLs; Hoody support can, when you ask for help.

  • The computer runs the Hoody Agent, and the Bot exists in it. A Bot URL points at one Bot of one computer, and a Bot has at most one Bot URL. To let more people in, give them more keys. A detached Bot URL still belongs to its Bot: re-point it or delete it before you create another one for that Bot.
  • The Agent must support Bot URLs. Creating a URL does not confirm compatibility. If public calls return 503 bot_upgrade_required, update the Agent.
  • The server that runs the computer has room for another Bot URL. See How many URLs a server allows.
  1. In the Hub, open Bots, select the Bot and open Link and keys.
  2. Choose Give it a link. Keep the suggested name or enter one under Name in the address. The label rules are under Labels.
  3. Leave Allow other websites (CORS) on unless you know no web page will call the Bot. See CORS.
  4. Choose Create link.
  5. Choose New key, enter a Name (who the key is for), then choose Make key.
  6. Copy the secret under Copy the key “name” now, then choose I’ve stored it. The secret is shown once.

In every tab, use the realm and id of the same Bot whose UID you pass. The examples use the global realm and chief, the Bot the agent creates in every realm.

The answer holds the URL and the starting status:

{
"statusCode": 201,
"data": {
"id": "bu_0123456789abcdef01234567",
"label": "amber-falcon-river-k7m2q",
"url": "https://amber-falcon-river-k7m2q.hoody.bot",
"realm": "global",
"owner_enabled": true,
"status": "active",
"status_reason": null,
"cors": true,
"limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 },
"test_curl": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/models -H \"Authorization: Bearer $HOODY_BOT_KEY\"",
"connect": {
"chat_page": "https://amber-falcon-river-k7m2q.hoody.bot",
"guide": "https://amber-falcon-river-k7m2q.hoody.bot/SKILL.md",
"openai_base_url": "https://amber-falcon-river-k7m2q.hoody.bot/v1",
"anthropic_base_url": "https://amber-falcon-river-k7m2q.hoody.bot",
"mcp_url": "https://amber-falcon-river-k7m2q.hoody.bot/mcp",
"key_header": "Authorization: Bearer $HOODY_BOT_KEY"
},
"keys": []
},
"propagation": { "state": "pending" }
}

connect says where each kind of client connects; every entry but the chat page and the guide needs a key (see What to paste where):

  • chat_page: the chat page, opened in a browser.
    https://<label>.hoody.bot
  • guide: the keyless guide as an agent skill.
    https://<label>.hoody.bot/SKILL.md
  • openai_base_url: the base URL of an OpenAI client (Chat Completions and Responses).
    https://<label>.hoody.bot/v1
  • anthropic_base_url: the base URL of an Anthropic client (Messages). It has no /v1.
    https://<label>.hoody.bot
  • mcp_url: an MCP client (Streamable HTTP).
    https://<label>.hoody.bot/mcp
  • key_header: the header that carries a key. Anthropic clients may send the key as x-api-key instead.
    Authorization: Bearer $HOODY_BOT_KEY

A new URL answers once propagation.state is applied and its address has reached DNS, usually within a minute. Read the URL again (GET /api/v1/bot-urls/{id}) to follow it.

When Bot URLs are unavailable, creating, enabling or re-pointing a URL and suggesting a label can return 503 BOTS_DISABLED. Address and connection-example fields (url, test_curl, connect, and a key’s curl, curl_chat and curl_mcp) may be null. You can still read or delete existing URLs, revoke keys and use panic; other writes remain subject to their usual checks.

In the agent’s BOTS mode, the Bot URLs tab lists your Bots’ public URLs: one row per Bot, with its URL, its status in words and how many keys it has. A Bot’s Connect window has a Public URL section too, with the URL, Copy, Open and a chip to the tab (Open Bot URLs while the Bot has no URL yet).

Select a Bot’s row in Bot URLs to act on it:

  • With no URL yet, + Create public URL asks for a name, already filled with a suggestion (Suggest a name gives another), and creates the URL.
  • + New key asks for the key’s name and shows the secret once, under Your new key, with the addresses to paste into OpenAI, Anthropic and MCP clients. Copy it then: it is not shown again.
  • Revoke… next to a key revokes it once you confirm with Revoke key. This cannot be undone.
  • Delete URL… deletes the URL once you confirm with Delete URL. Every key stops working, and the name stays taken forever.
  • Open opens the URL in a browser, where the chat page is; Copy copies it.

Rotating keys, a key’s other settings (pause, IPv4 list, expiry), the URL’s settings, re-pointing and panic stay in the Hub and the Hoody API.

The agent acts with its own Hoody login, so that login needs the same rights as a token: it belongs to the project’s owner and allows Bot URLs. A login limited to some realms is refused with Public URLs need a Hoody login for all realms, and this agent’s login is limited to some realms. Sign the agent in with a login for all realms, or manage public URLs in the Hub. An agent that says its Hoody connector is too old needs an update first.

The label is the first part of the address. The default, a generated label, is three short words and five characters, for example amber-falcon-river-k7m2q. It is hard to guess and never looks like a brand.

To choose your own, follow these rules. A label that breaks one is refused as it is; nothing is lowercased, trimmed or converted for you.

RuleExample that fails
8 to 48 charactersmy-bot (too short)
Lowercase ASCII letters a-z, digits 0-9 and single hyphens onlyMy-Bot-2026, my_bot_2026, bot.example
Starts with a letter2026-helper
Ends with a letter or a digithelper-bot-
No two hyphens in a rowhelper--bot, xn--helper
No spaces, accents or other characters outside a-z 0-9 -café-helper, helper bot

Two more rules apply:

  • A label is yours forever, and only once. Every label ever created stays taken, even after its URL is deleted. Nobody can take it over later, and you cannot reuse it either.
  • Some labels are reserved, such as brand, product and service names (hoody-bot, official, customer-support). A reserved label is refused.
ErrorMeaning
400 BOT_LABEL_INVALIDThe label breaks one of the rules above.
409 BOT_LABEL_RESERVEDThe label is on the reserved list.
409 BOT_LABEL_TAKENThe label was used before, by anyone.
429 BOT_LABEL_THROTTLEDYou already created 10 Bot URLs in the last hour, so an 11th is refused. The count is per account, over a rolling hour, and deleted URLs count too. Wait and try again.

GET /api/v1/bot-urls/suggest-label returns a fresh generated label without reserving it.

A key opens the URL. Make one key per person or app, and name it after them: alice, zapier, ci. The Bot sees the name with every message, and the access log records it with every call.

Replace 203.0.113.0/24 in the examples with the public IPv4 address or range the key will be used from, or leave out ipv4_allow to allow every IPv4 address.

On Link and keys, choose New key. Enter Name and, optionally, Allowed addresses, Expires on, Notes and Note for the holder. Choose Make key, copy the secret, then choose I’ve stored it. If you lose the secret, rotate the key to get a new one.

{
"statusCode": 201,
"data": {
"key": {
"id": "bk_89abcdef0123456789abcdef",
"name": "alice",
"prefix": "hbk_x7Qm2LpA",
"enabled": true,
"ipv4_allow": ["203.0.113.0/24"],
"expires_at": "2027-01-31T00:00:00.000Z",
"notes": "Alice at Example Ltd, contract until January",
"status": "active"
},
"secret": "hbk_x7Qm2LpA…",
"curl": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/models -H \"Authorization: Bearer hbk_x7Qm2LpA…\"",
"curl_chat": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/chat/completions -H \"Authorization: Bearer hbk_x7Qm2LpA…\" -H \"Content-Type: application/json\" -d '{\"model\":\"bot\",\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'",
"curl_mcp": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/mcp -H \"Authorization: Bearer hbk_x7Qm2LpA…\" -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'"
},
"propagation": { "state": "pending" }
}

The curl line is a test call with the new secret written into it; curl_chat sends the Bot one message through the OpenAI door and curl_mcp lists its MCP tools, the same way. Running them as they are puts the secret on a command line, where other programs on the machine can read it. Store the secret in HOODY_BOT_KEY instead and send it on standard input, as in Test the key. The three lines may be null while Bot URLs are unavailable. Keys remain stored, but calls are refused with bot_disabled while Bot URLs are disabled; you can still revoke keys.

A secret starts with hbk_ followed by 43 letters and digits. The first 12 characters, the prefix, stay visible in the key table so you can tell keys apart.

FieldWhat it does
name1 to 32 characters: letters, digits, spaces, ., _ and -, starting and ending with a letter or digit. Unique among the URL’s keys, ignoring case.
enabledfalse pauses the key. Calls with it are refused with key_disabled until you turn it back on. Nothing else changes.
ipv4_allowUp to 32 IPv4 addresses or CIDR ranges, such as 198.51.100.7 or 203.0.113.0/24. Calls from any other address are refused with ip_not_allowed. An empty list allows every IPv4 address. IPv6 entries are refused.
expires_atA UTC date and time after which the key stops working (key_disabled). null means no expiry. In the Hub you pick a day, and the key stops working at the end of that day (UTC).
notesUp to 500 characters for yourself. Only you see notes; they never reach the Bot or the caller.
holder_noteUp to 1,000 characters of plain text for the key holder. Set it on create or update; the CLI uses --holder-note. Empty or null clears it. The holder reads it with GET /v1/key and on the chat page.

A URL holds up to 20 keys. Revoked keys do not count.

ActionHubAPI
Pause or resumePause or ResumePATCH …/keys/{keyId} with {"enabled": false} to pause or {"enabled": true} to resume
Change addresses, expiry, name or noteEditPATCH …/keys/{keyId}
New secret, same keyRotatePOST …/keys/{keyId}/rotate
Remove for goodRevokeDELETE …/keys/{keyId}
Remove every keyRevoke all keysPOST …/keys/revoke-all

… stands for https://api.hoody.com/api/v1/bot-urls/{id}. The CLI has the same actions as hoody boturls keys update, rotate, revoke and revoke --all, and the SDK as client.api.botUrls.keys.update(), rotate(), revoke() and revokeAll(). After a rotate or a revoke, the old secret can keep working for a short while: until the change is applied, and then for up to about 11 seconds more. A revoked key cannot be brought back; make a new one.

Every write answers with a propagation block. Once its state is applied, new calls see the change within about 11 seconds. A call already running when you revoke a key or pause the URL finishes. An open event stream stops sending events within about a minute after applied, typically about 36 seconds: each stream ends after about 25 seconds, and the reconnect is refused. Work the Bot already handed to its agents keeps going; stop it in the agent if you need to.

propagation.stateMeaning
appliedThe change is in place.
pendingThe change is on its way. Read the URL again in a few seconds.
failedThe change could not be put in place yet. It is retried; read the URL again later.
unknownHoody cannot tell yet. Treat it as pending.
supersededA newer change replaced this one. Follow the newer one.

Panic turns the URL off and revokes every key in one step. Use it when a key leaked and you do not know which one.

On Link and keys, choose Panic: turn the link off and confirm with Turn off and revoke. The Hub shows the propagation state until the change is applied.

The answer carries a propagation block, like every write; read the URL again (GET /api/v1/bot-urls/{id}) until its state is applied. Panic does not stop work the Bot is already doing. Open the Bot in the agent and stop it there. To use the URL again, turn it back on (PATCH /api/v1/bot-urls/{id} with {"enabled": true}) and create new keys.

FieldDefaultWhat it does
enabledtruefalse turns the URL off (Turn link off and Turn link on in the Hub; owner_enabled when you read it). Callers with a valid key get bot_disabled. Keys are kept.
corstrueLets pages on other websites call the URL from a browser. Turning it off leaves the Bot’s own chat page working. See CORS.
iframablefalsePermits other websites to load the Bot page in a frame. A website frame shows a link to open the chat in a new tab. Turn this on after creation with PATCH /api/v1/bot-urls/{id} or CLI --iframable; use --no-iframable to turn it off.
limits.key_rpm60Requests per minute for each key (1 to 600).
limits.bot_rpm120Requests per minute for the whole URL, all keys together (1 to 3000).
limits.key_concurrency4Calls at the same time for each key (1 to 16).
limits.bot_concurrency8Calls at the same time for the whole URL (1 to 32).

Change CORS and request limits in the Hub under Limits and websites. Use Turn link off or Turn link on for enabled, and the API or CLI for iframable. You can also update URL settings with PATCH /api/v1/bot-urls/{id}, hoody boturls update $BOT_URL_ID --limits-key-rpm 30 or client.api.botUrls.update(BOT_URL_ID, { limits: { key_rpm: 30 } }). Sending limits replaces the whole limits block; omitted members return to their defaults. To change one limit and keep the others, read the current limits and send all four values with the change.

If your account has 2FA and requires it for API keys, a session must send an unused current or backup code as otp_code when creating, rotating or resuming a key; changing its address list or expiry; turning on a URL, browser access or framing; changing limits; or re-pointing a URL. The CLI accepts --otp-code. A missing code returns 400 OTP_REQUIRED; an invalid or already used code returns 401 INVALID_OTP_CODE. With password Basic authentication, the operation uses the code supplied at authentication. API-token authentication needs no additional code.

Each server allows a set number of Bot URLs for the computers it runs: 5 on a free server, 25 on Plus, 250 on Pro and 5,000 on a bare-metal server (see Pricing). On a paid subserver the number is its plan’s max_bot_urls, and a plan change never lowers it. A URL counts against the server of its computer while it is attached, even when it is turned off, frozen or suspended. A detached or deleted URL counts against no server.

When the server is full, creation and re-pointing from another server or from a detached URL are refused. Re-pointing an attached URL between computers on the same server uses its existing slot, so the Bot URL limit does not refuse it:

{
"statusCode": 400,
"error": "SERVER_BOT_URL_LIMIT",
"message": "This server has reached its Bot URL limit (5/5). Delete or re-point an existing Bot URL first.",
"data": { "field": "server_bot_url_limit", "server_id": "…", "max": 5, "used": 5 }
}
ErrorMeaning
409 BOT_URL_EXISTSThe Bot already has a Bot URL. Add a key to it instead.
403 BOT_URL_OWNER_ONLYYou can use the computer, but you do not own its project. Ask the owner.
404 BOT_URL_NOT_FOUNDNo such URL, it is not yours, or it belongs to a realm your token cannot use.
409 BOT_URL_FROZENHoody froze this URL. It cannot be turned on or re-pointed until it is unfrozen.
404 BOT_KEY_NOT_FOUNDNo such key on this URL.
409 BOT_KEY_NAME_TAKENAnother key on this URL already has that name.
400 BOT_KEY_LIMITThe URL already has 20 keys. Revoke one first.
400 BOT_REALM_INVALIDThe Bot’s realm is not allowed for this computer, or for the realm your token is limited to.
400 BOT_IPV4_INVALIDAn ipv4_allow entry is not a plain IPv4 address or CIDR range: leading zeros (010.0.0.1), host bits set in a range (203.0.113.5/24), or more than 32 entries. IPv6 is refused in every spelling. Duplicate entries are merged.
400 BOT_FIELD_INVALIDA field is out of range, has the wrong type, or is not a known field. data.field names it. Nothing is changed for you or dropped.
429 RATE_LIMIT_EXCEEDEDToo many changes in a short time. Every change counts, on the URL and its keys: create, update, re-point, panic, delete, and key create, update, rotate and revoke. Reads do not. Wait the seconds in Retry-After. This is separate from BOT_LABEL_THROTTLED and from the rate_limited callers of the URL get.
404 COMPUTER_NOT_FOUNDOn create or re-point: the computer does not exist, or you cannot access it. Check the computer id.
400 OTP_REQUIREDYour account requires a 2FA code for this change. Send otp_code. See Two-factor codes on changes.
401 INVALID_OTP_CODEThe 2FA code is wrong or already used. Send a fresh one.
409 SUBSERVER_DORMANTThe paid server is on hold; the requested change cannot be made now.
503 BOTS_DISABLEDBot URLs are unavailable right now. Creating, enabling or re-pointing a URL and suggesting a label are refused; reading, deleting, revoking keys and panic still work.
503 BOT_LABEL_GENERATION_FAILEDNo free generated name was found. Retry.