# Documentation Page
**Page:** kit/agent/bot-urls/create
[Download Raw Markdown](./kit/agent/bot-urls/create.md)
---
# Create a Bot URL and keys
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.
## Before you start
- 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](#how-many-urls-a-server-allows).
## Create the URL
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](#labels).
3. Leave **Allow other websites (CORS)** on unless you know no web page will call the Bot. See [CORS](/kit/agent/bot-urls/security/#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.
Run these on a machine you trust: `-H "Authorization: Bearer $HOODY_TOKEN"` puts your account token in the command line, where other programs on the machine can read it. To keep it off, send the header on standard input instead, as in [Test the key](/kit/agent/bot-urls/calling/#test-the-key): `printf 'Authorization: Bearer %s\n' "$HOODY_TOKEN" | curl … --header @-`.
```bash
# Create a Bot URL with a generated label
curl -X POST https://api.hoody.com/api/v1/bot-urls \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"computer_id": "'"$COMPUTER_ID"'",
"bot": { "realm": "global", "id": "chief", "uid": "'"$BOT_UID"'" }
}'
```
`bot.uid` is the Bot's unique id, the top-level `uid` in `GET /api/v1/agent/bots/{id}` on the computer's agent URL. A Bot that is deleted and created again under the same id gets a new UID, so a Bot URL never moves to a different Bot by accident. Add `"label": "acme-helper"` to choose the label, and `"cors": false` to prevent browser calls from other websites. The Bot's own chat page still works.
The token needs the `resources.bot_urls` permission. Not every token created before Bot URLs existed got it: full-access tokens and tokens that could manage proxy aliases did, provided every token above them in the creator chain held it too. Tokens that already had an explicit `resources.bot_urls` value, including `false`, kept it. Any other token needs `resources.bot_urls` added to its permissions. A token restricted to realms must call its realm's API address, `https://{realmId}.api.hoody.com`, not `api.hoody.com`: on the base address it is refused with `403`. On its realm address it can create and manage Bot URLs for Bots of that realm only; a Bot URL of another realm answers `BOT_URL_NOT_FOUND`.
```bash
# Create a Bot URL with a generated label
hoody boturls create --computer-id $COMPUTER_ID \
--bot-realm global --bot-id chief --bot-uid $BOT_UID
# Or pick the label yourself; `hoody boturls label suggest` proposes a free one
hoody boturls create --computer-id $COMPUTER_ID \
--bot-realm global --bot-id chief --bot-uid $BOT_UID --label acme-helper
```
```typescript
const { data, propagation } = await client.api.botUrls.create({
computer_id: COMPUTER_ID,
bot: { realm: 'global', id: 'chief', uid: BOT_UID },
label: 'acme-helper', // optional; leave it out for a generated label
});
// Follow the change until it is applied
const current = await client.api.botUrls.get(data.id);
console.log(current.propagation.state);
```
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:
```json
{
"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](/kit/agent/bot-urls/calling/#what-to-paste-where)):
- `chat_page`: the chat page, opened in a browser. `https://.hoody.bot`
- `guide`: the keyless guide as an agent skill. `https://.hoody.bot/SKILL.md`
- `openai_base_url`: the base URL of an OpenAI client (Chat Completions and Responses). `https://.hoody.bot/v1`
- `anthropic_base_url`: the base URL of an Anthropic client (Messages). It has no `/v1`. `https://.hoody.bot`
- `mcp_url`: an MCP client (Streamable HTTP). `https://.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.
### From the agent
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](/kit/agent/bot-urls/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.
## Labels
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.
| Rule | Example that fails |
|---|---|
| 8 to 48 characters | `my-bot` (too short) |
| Lowercase ASCII letters `a-z`, digits `0-9` and single hyphens only | `My-Bot-2026`, `my_bot_2026`, `bot.example` |
| Starts with a letter | `2026-helper` |
| Ends with a letter or a digit | `helper-bot-` |
| No two hyphens in a row | `helper--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.
| Error | Meaning |
|---|---|
| `400 BOT_LABEL_INVALID` | The label breaks one of the rules above. |
| `409 BOT_LABEL_RESERVED` | The label is on the reserved list. |
| `409 BOT_LABEL_TAKEN` | The label was used before, by anyone. |
| `429 BOT_LABEL_THROTTLED` | You 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.
## Keys
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.
```bash
# Create a key named alice that works only from one office network
curl -X POST https://api.hoody.com/api/v1/bot-urls/$BOT_URL_ID/keys \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "alice",
"ipv4_allow": ["203.0.113.0/24"],
"expires_at": "2027-01-31T00:00:00.000Z",
"notes": "Alice at Example Ltd, contract until January"
}'
```
```bash
# Create a key named alice that works only from one office network
hoody boturls keys create $BOT_URL_ID --name alice \
--ipv4-allow 203.0.113.0/24 \
--expires-at 2027-01-31T00:00:00.000Z \
--notes "Alice at Example Ltd, contract until January"
```
```typescript
const { data } = await client.api.botUrls.keys.create(BOT_URL_ID, {
name: 'alice',
ipv4_allow: ['203.0.113.0/24'],
expires_at: '2027-01-31T00:00:00.000Z',
notes: 'Alice at Example Ltd, contract until January',
});
console.log(data.secret); // shown once: store it now
```
```json
{
"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" }
}
```
Hoody stores only a fingerprint of the secret, so nobody can show it to you again. If it is lost, rotate the key: it keeps its name and settings and gets a new secret.
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](/kit/agent/bot-urls/calling/#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.
### What you can set on a key
| Field | What it does |
|---|---|
| `name` | 1 to 32 characters: letters, digits, spaces, `.`, `_` and `-`, starting and ending with a letter or digit. Unique among the URL's keys, ignoring case. |
| `enabled` | `false` pauses the key. Calls with it are refused with `key_disabled` until you turn it back on. Nothing else changes. |
| `ipv4_allow` | Up 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_at` | A 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). |
| `notes` | Up to 500 characters for yourself. Only you see notes; they never reach the Bot or the caller. |
| `holder_note` | Up 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](/kit/agent/bot-urls/chat-page/). |
A URL holds up to 20 keys. Revoked keys do not count.
### Change, rotate and revoke
| Action | Hub | API |
|---|---|---|
| Pause or resume | **Pause** or **Resume** | `PATCH …/keys/{keyId}` with `{"enabled": false}` to pause or `{"enabled": true}` to resume |
| Change addresses, expiry, name or note | **Edit** | `PATCH …/keys/{keyId}` |
| New secret, same key | **Rotate** | `POST …/keys/{keyId}/rotate` |
| Remove for good | **Revoke** | `DELETE …/keys/{keyId}` |
| Remove every key | **Revoke all keys** | `POST …/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.
### When a change takes effect
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](/kit/agent/bot-urls/calling/#live-events) 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.state` | Meaning |
|---|---|
| `applied` | The change is in place. |
| `pending` | The change is on its way. Read the URL again in a few seconds. |
| `failed` | The change could not be put in place yet. It is retried; read the URL again later. |
| `unknown` | Hoody cannot tell yet. Treat it as `pending`. |
| `superseded` | A newer change replaced this one. Follow the newer one. |
## The panic button
**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.
```bash
curl -X POST https://api.hoody.com/api/v1/bot-urls/$BOT_URL_ID/panic \
-H "Authorization: Bearer $HOODY_TOKEN"
```
```bash
hoody boturls panic $BOT_URL_ID --yes
```
```typescript
await client.api.botUrls.panic(BOT_URL_ID);
```
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.
## URL settings
| Field | Default | What it does |
|---|---|---|
| `enabled` | `true` | `false` 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. |
| `cors` | `true` | Lets pages on other websites call the URL from a browser. Turning it off leaves the Bot's own chat page working. See [CORS](/kit/agent/bot-urls/security/#cors). |
| `iframable` | `false` | Permits 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_rpm` | 60 | Requests per minute for each key (1 to 600). |
| `limits.bot_rpm` | 120 | Requests per minute for the whole URL, all keys together (1 to 3000). |
| `limits.key_concurrency` | 4 | Calls at the same time for each key (1 to 16). |
| `limits.bot_concurrency` | 8 | Calls 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.
## Two-factor codes on changes
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.
## How many URLs a server allows
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](/foundation/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:
```json
{
"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 }
}
```
## Other errors
| Error | Meaning |
|---|---|
| `409 BOT_URL_EXISTS` | The Bot already has a Bot URL. Add a key to it instead. |
| `403 BOT_URL_OWNER_ONLY` | You can use the computer, but you do not own its project. Ask the owner. |
| `404 BOT_URL_NOT_FOUND` | No such URL, it is not yours, or it belongs to a realm your token cannot use. |
| `409 BOT_URL_FROZEN` | Hoody froze this URL. It cannot be turned on or re-pointed until it is unfrozen. |
| `404 BOT_KEY_NOT_FOUND` | No such key on this URL. |
| `409 BOT_KEY_NAME_TAKEN` | Another key on this URL already has that name. |
| `400 BOT_KEY_LIMIT` | The URL already has 20 keys. Revoke one first. |
| `400 BOT_REALM_INVALID` | The Bot's realm is not allowed for this computer, or for the realm your token is limited to. |
| `400 BOT_IPV4_INVALID` | An `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_INVALID` | A 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_EXCEEDED` | Too 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_FOUND` | On create or re-point: the computer does not exist, or you cannot access it. Check the computer id. |
| `400 OTP_REQUIRED` | Your account requires a 2FA code for this change. Send `otp_code`. See [Two-factor codes on changes](#two-factor-codes-on-changes). |
| `401 INVALID_OTP_CODE` | The 2FA code is wrong or already used. Send a fresh one. |
| `409 SUBSERVER_DORMANT` | The paid server is on hold; the requested change cannot be made now. |
| `503 BOTS_DISABLED` | Bot 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_FAILED` | No free generated name was found. Retry. |
## What's Next
- [Call a Bot URL](/kit/agent/bot-urls/calling/): what to send the people who use your keys.
- [Status, access log and lifecycle](/kit/agent/bot-urls/status/): follow calls, move a URL to another computer, delete it.
- [Security](/kit/agent/bot-urls/security/): what a key holder can do, CORS and IPv4.