# 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://