Bot URLs
Section titled “Bot URLs”A Bot URL gives a Hoody Bot in one of your computers a stable public address of the form https://<label>.hoody.bot that callers reach with a named key. Each Bot has at most one Bot URL, and the URL may carry many keys, one for each caller, team, or environment. Bot URL ids use the bu_… prefix, and key ids use the bk_… prefix.
Use these endpoints to list, create, re-point, update, panic, and delete Bot URLs, and to create, rotate, update, revoke, or revoke all their keys. Token credentials must include the resources.bot_urls permission.
If the platform’s Bot URL domain is not set up, url, test_curl, connect, and a key’s curl, curl_chat, and curl_mcp are null, so no address is shown. Creating, turning on, and re-pointing a URL are then refused with 503 BOTS_DISABLED. The same three operations are refused while Bot URLs are switched off platform-wide, but the address-related fields are not null in that case. Reads, settings that turn the URL off, delete, keys including revocation, and panic continue to work in both cases.
Conceptual guides:
- Bot URLs overview
- Create a Bot URL
- How callers use a URL and key
- Caller-side error codes and limits
- Status, propagation, and reads
In the Hub, open Bots, select the Bot and open Link and keys. Give it a link, then Create link; choose New key, then Make key, and keep the secret shown once. Existing keys offer Edit, Pause, Resume, Rotate and Revoke.
List and read
Section titled “List and read”GET /api/v1/bot-urls/suggest-label
Section titled “GET /api/v1/bot-urls/suggest-label”Returns a generated label that is free right now, such as amber-falcon-river-k7m2q, and the URL that a Bot URL created with the label would receive. The label is not reserved until a Bot URL is created with it. This endpoint answers 503 BOTS_DISABLED while Bot URLs are unavailable on the platform, in the same conditions that prevent creation.
This endpoint takes no parameters.
curl -X GET 'https://api.hoody.com/api/v1/bot-urls/suggest-label' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.suggestLabel();Response
Section titled “Response”A free label and its URL were generated.
Media type: application/json
{ "statusCode": 200, "message": "Suggested Bot name", "data": { "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot" }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
Bot URLs are unavailable, or no free generated label was found.
Media type: application/json
{ "statusCode": 503, "error": "BOT_LABEL_GENERATION_FAILED", "message": "Could not generate a free Bot name; retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOTS_DISABLED | Bot URLs unavailable | Bot URLs are switched off on this platform, or its Bot URL domain is not set up. Creating, turning on, re-pointing, and suggesting a name are refused. Reads, settings, delete, keys, and panic still work. While the domain is not set up, url, test_curl, connect, and the key curl lines are null. | Retry later. |
BOT_LABEL_GENERATION_FAILED | No free generated name | A free generated label could not be found. | Retry. |
GET /api/v1/bot-urls
Section titled “GET /api/v1/bot-urls”Returns Bot URLs of projects you own, newest first, one page at a time. Pass data.next_cursor from the response back as cursor to fetch the next page. A null next_cursor means the last page. Filter by project_id or computer_id. A filter naming a project or computer you do not own returns an empty list. Auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
project_id | query | string | No | Filter to one project id |
computer_id | query | string | No | Filter to one computer id |
limit | query | integer | No | Bot URLs per page, from 1 to 100. Default: 50 |
cursor | query | string | No | The next_cursor returned by the previous page |
curl -X GET 'https://api.hoody.com/api/v1/bot-urls?limit=25' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”The HTTP endpoint returns one page per request. The SDK’s listIterator helper yields one Bot URL at a time and sends each page request when iterated.
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
for await (const botUrl of client.api.botUrls.listIterator({ limit: 25 })) { console.log(botUrl.label, botUrl.status);}Response
Section titled “Response”A page of Bot URLs was returned.
Media type: application/json
{ "statusCode": 200, "message": "Bot URLs", "data": { "bot_urls": [ { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "890abcdef12345678901cdef", "server_id": "67e89abc123def456789abcd", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "active", "status_reason": null, "frozen": null, "revision": 7, "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": [ { "id": "bk_89abcdef0123456789abcdef", "name": "support-team", "prefix": "hbk_4f9a2c1e", "enabled": true, "ipv4_allow": [ "203.0.113.0/24" ], "expires_at": null, "notes": "Issued for the front-line support team; expires are managed manually.", "holder_note": null, "status": "active", "created_at": "2026-04-12T10:14:23Z", "rotated_at": null } ], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-05-03T16:42:01Z" } ], "next_cursor": null }}The request uses a retired API name. Nothing was changed.
Media type: application/json
{ "statusCode": 400, "error": "UPGRADE_REQUIRED", "message": "This Hoody CLI is too old for the renamed API. Update: npm i -g hoody-sdk@1.0.1"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
UPGRADE_REQUIRED | Request uses a retired name | The request uses a retired API name or comes from a Hoody CLI too old for the current API. Nothing was changed. | Send the replacement listed in data.renamed, or update the Hoody CLI and SDK. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The cursor is not valid for this endpoint.
Media type: application/json
{ "statusCode": 422, "error": "INVALID_CURSOR", "message": "Invalid cursor"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_CURSOR | Invalid cursor | The cursor is not one this endpoint returned. | Pass next_cursor from the previous page unchanged, or omit it to start from the first page. |
GET /api/v1/bot-urls/{id}
Section titled “GET /api/v1/bot-urls/{id}”Returns the full state of one Bot URL: status and reason, keys without secrets, a copyable test_curl, connection details, and the latest propagation snapshot. After a change, poll this endpoint until propagation.state is applied. After a delete, it answers 404 BOT_URL_NOT_FOUND right away, which does not mean the removal is applied. The DELETE reply carries the removal’s propagation.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
curl -X GET 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.get('bu_0123456789abcdef01234567');Response
Section titled “Response”The Bot URL and its latest propagation state were returned.
Media type: application/json
{ "statusCode": 200, "message": "Bot URL", "data": { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "890abcdef12345678901cdef", "server_id": "67e89abc123def456789abcd", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "active", "status_reason": null, "frozen": null, "revision": 7, "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": [ { "id": "bk_89abcdef0123456789abcdef", "name": "support-team", "prefix": "hbk_4f9a2c1e", "enabled": true, "ipv4_allow": [ "203.0.113.0/24" ], "expires_at": null, "notes": "Issued for the front-line support team; expires are managed manually.", "holder_note": null, "status": "active", "created_at": "2026-04-12T10:14:23Z", "rotated_at": null } ], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-05-03T16:42:01Z" }, "propagation": { "committed": true, "complete": true, "state": "applied", "generation": 7, "action": "upsert", "succeeded_count": 3, "failed_count": 0, "pending_count": 0, "target_count": 3, "deny_targets": [] }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
Create and manage Bot URLs
Section titled “Create and manage Bot URLs”POST /api/v1/bot-urls
Section titled “POST /api/v1/bot-urls”Creates a Bot URL for an agent Bot in one of your computers. Omit label to receive a generated one. GET /api/v1/bot-urls/suggest-label returns a free label on demand. The URL has no keys when it is created. Create one with POST /api/v1/bot-urls/{id}/keys. The new URL counts against the hosting server’s Bot URL limit.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
computer_id | string | Yes | Id of the computer hosting the agent Bot |
bot | object | Yes | The agent Bot the URL serves |
bot.realm | string | Yes | global or a realm of the destination computer |
bot.id | string | Yes | Bot id, up to 64 characters |
bot.uid | string | Yes | Bot UID, up to 36 characters |
label | string | No | 8 to 48 characters, lowercase letters, digits, and single hyphens. Starts with a letter and ends with a letter or digit. |
cors | boolean | No | Allow browser calls. Default: true |
iframable | boolean | No | Only false is accepted here. Default: false. Turn it on after creation by changing the Bot URL. |
limits | object | No | Request limits |
limits.key_rpm | integer | No | Per-key requests per minute, from 1 to 600. Default: 60 |
limits.bot_rpm | integer | No | Per-Bot requests per minute, from 1 to 3000. Default: 120 |
limits.key_concurrency | integer | No | Per-key concurrent calls, from 1 to 16. Default: 4 |
limits.bot_concurrency | integer | No | Per-Bot concurrent calls, from 1 to 32. Default: 8 |
{ "computer_id": "890abcdef12345678901cdef", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "label": "amber-falcon-river-k7m2q", "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }}curl -X POST 'https://api.hoody.com/api/v1/bot-urls' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "computer_id": "890abcdef12345678901cdef", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "label": "amber-falcon-river-k7m2q", "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 } }'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.create({ computer_id: '890abcdef12345678901cdef', bot: { realm: 'global', id: 'support-bot', uid: '1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f', }, label: 'amber-falcon-river-k7m2q', cors: true, iframable: false, limits: { key_rpm: 60, bot_rpm: 120, key_concurrency: 4, bot_concurrency: 8, },});Response
Section titled “Response”The Bot URL was created.
Media type: application/json
{ "statusCode": 201, "message": "Bot URL created", "data": { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "890abcdef12345678901cdef", "server_id": "67e89abc123def456789abcd", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "active", "status_reason": null, "frozen": null, "revision": 1, "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": [], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-04-12T10:14:23Z" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 1, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A label, field, realm, server limit, or request value was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_LABEL_INVALID", "message": "label must start with a letter"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_LABEL_INVALID | Invalid Bot name | The label must be 8 to 48 characters of lowercase letters, digits, and single hyphens. It must start with a letter and end with a letter or digit. It is checked exactly as sent. Nothing is lowercased or trimmed. | Send a valid label, or omit it to get a generated one. |
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
BOT_REALM_INVALID | Bot realm not allowed | bot.realm must be global or a realm the destination computer belongs to. On a realm URL, it must be that realm. | Send the realm the agent reports for this Bot, from a URL that allows it. |
SERVER_BOT_URL_LIMIT | Server Bot URL limit reached | The server hosting the computer already has its maximum number of attached Bot URLs. The response carries data: {field: "server_bot_url_limit", server_id, max, used}. | Delete or re-point a Bot URL on that server. |
UPGRADE_REQUIRED | Request uses a retired name | The request uses a retired API name or comes from a Hoody CLI too old for the current API. Nothing was changed. | Send the replacement listed in data.renamed, or update the Hoody CLI and SDK. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The destination computer was not found.
Media type: application/json
{ "statusCode": 404, "error": "COMPUTER_NOT_FOUND", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist, or you do not have permission to access it. | Verify the computer id is correct and that you have access to the project it belongs to. |
The label, Bot, server, or computer prevented creation.
Media type: application/json
{ "statusCode": 409, "error": "BOT_URL_EXISTS", "message": "This Bot already has a Bot URL. Use or re-point that one."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_LABEL_RESERVED | Reserved Bot name | The label is on the reserved list. | Choose another label. |
BOT_LABEL_TAKEN | Bot name already taken | Every label ever created stays taken forever, including after its Bot URL is deleted. | Choose another label. |
BOT_URL_EXISTS | Bot already has a URL | Each Bot has at most one Bot URL. It can carry many named keys. | Use the existing Bot URL, add a key to it, or re-point it. |
BOT_FIELD_INVALID | Computer cannot hold a Bot URL | The computer cannot hold a Bot URL in its current state because it failed, is being deleted, was deleted, or is not yet placed on a server. data.field is computer_id. | Choose a computer that is placed on a server and is not failed or deleted, or retry once it is placed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "BOT_LABEL_THROTTLED", "message": "At most 10 Bot URLs can be created per hour"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_LABEL_THROTTLED | Too many Bot URLs created | At most 10 Bot URLs can be created per account per hour. | Wait and retry. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Bot URLs are unavailable, or a generated label could not be found.
Media type: application/json
{ "statusCode": 503, "error": "BOTS_DISABLED", "message": "Bot URLs are not available right now"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOTS_DISABLED | Bot URLs unavailable | Bot URLs are switched off on this platform, or its Bot URL domain is not set up. Creating, turning on, re-pointing, and suggesting a name are refused. Reads, settings, delete, keys, and panic still work. While the domain is not set up, url, test_curl, connect, and the key curl lines are null. | Retry later. |
BOT_LABEL_GENERATION_FAILED | No free generated name | A free generated label could not be found. | Retry. |
PATCH /api/v1/bot-urls/{id}
Section titled “PATCH /api/v1/bot-urls/{id}”Changes the URL settings. You can turn the URL on or off, allow or refuse browser calls, let other websites show the Bot page in a frame, or change request limits.
Turning the URL on is refused while it is frozen with 409 BOT_URL_FROZEN, or while Bot URLs are switched off on the platform or its Bot URL domain is not set up with 503 BOTS_DISABLED. Turning it off remains available.
Turning it on, allowing browser calls, allowing frames, or changing limits needs otp_code when your account requires 2FA for API keys. Turning it off, refusing browser calls, or refusing frames does not.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | The owner switch. true turns the URL on, and false turns it off. |
cors | boolean | No | Allow or refuse browser calls |
iframable | boolean | No | Allow or refuse other websites to show the Bot page in a frame |
limits | object | No | New request limits |
limits.key_rpm | integer | No | Per-key requests per minute, from 1 to 600. Default: 60 |
limits.bot_rpm | integer | No | Per-Bot requests per minute, from 1 to 3000. Default: 120 |
limits.key_concurrency | integer | No | Per-key concurrent calls, from 1 to 16. Default: 4 |
limits.bot_concurrency | integer | No | Per-Bot concurrent calls, from 1 to 32. Default: 8 |
otp_code | string | No | Current 2FA code or backup code. Required only when your account has 2FA enabled and requires it for API keys. An unused code is required, and a code already used is refused. |
{ "enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 120, "bot_rpm": 240 }}curl -X PATCH 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "enabled": false }'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.update('bu_0123456789abcdef01234567', { enabled: false,});Response
Section titled “Response”The Bot URL settings were changed.
Media type: application/json
{ "statusCode": 200, "message": "Bot URL updated", "data": { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "890abcdef12345678901cdef", "server_id": "67e89abc123def456789abcd", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 120, "bot_rpm": 240, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "active", "status_reason": null, "frozen": null, "revision": 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": [], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-05-03T16:42:01Z" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 8, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A field, limit, or 2FA requirement was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_FIELD_INVALID", "message": "enabled must be boolean", "data": { "field": "enabled" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
OTP_REQUIRED | 2FA verification required | An unused otp_code is required only when the account has 2FA enabled and requires it for API keys. | Provide an unused otp_code with a valid TOTP code or backup code. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
The Bot URL is frozen, or its computer cannot be changed.
Media type: application/json
{ "statusCode": 409, "error": "BOT_URL_FROZEN", "message": "This Bot URL is frozen by an administrator"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_FROZEN | Bot URL frozen | An administrator froze this Bot URL. It cannot be turned on or re-pointed. | Contact support. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
TWOFACTOR_RATE_LIMIT | 2FA verification locked | Too many failed 2FA codes. 2FA checks are refused for up to 15 minutes; data.lockout_seconds says how long is left. | Wait data.lockout_seconds seconds, then try again with a current code. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Bot URLs are unavailable.
Media type: application/json
{ "statusCode": 503, "error": "BOTS_DISABLED", "message": "Bot URLs are not available right now"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOTS_DISABLED | Bot URLs unavailable | Bot URLs are switched off on this platform, or its Bot URL domain is not set up. Creating, turning on, re-pointing, and suggesting a name are refused. Reads, settings, delete, keys, and panic still work. While the domain is not set up, url, test_curl, connect, and the key curl lines are null. | Retry later. |
POST /api/v1/bot-urls/{id}/repoint
Section titled “POST /api/v1/bot-urls/{id}/repoint”Moves the URL to a Bot in another computer you own, for example after copying a computer. The label and keys are kept. The destination server’s limit is checked. A detached URL is attached again, and its state is then derived from its other facts. An owner switch that is off or a suspension still applies.
Re-pointing a frozen URL is refused with 409 BOT_URL_FROZEN. The operation needs otp_code when your account requires 2FA for API keys. The URL’s keys then reach the new Bot.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
computer_id | string | Yes | Id of the destination computer |
bot | object | Yes | The agent Bot now served by the URL |
bot.realm | string | Yes | global or a realm of the destination computer |
bot.id | string | Yes | Bot id, up to 64 characters |
bot.uid | string | Yes | Bot UID, up to 36 characters |
otp_code | string | No | Current 2FA code or backup code. Required only when your account has 2FA enabled and requires it for API keys. An unused code is required, and a code already used is refused. |
{ "computer_id": "0123456789abcdef01234567", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }}curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/repoint' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "computer_id": "0123456789abcdef01234567", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" } }'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.repoint('bu_0123456789abcdef01234567', { computer_id: '0123456789abcdef01234567', bot: { realm: 'global', id: 'support-bot', uid: '1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f', },});Response
Section titled “Response”The Bot URL was re-pointed.
Media type: application/json
{ "statusCode": 200, "message": "Bot URL re-pointed", "data": { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "0123456789abcdef01234567", "server_id": "0123456789abcdef01234567", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": true, "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "active", "status_reason": null, "frozen": null, "revision": 9, "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": [], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-05-03T18:00:00Z" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 9, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A field, realm, server limit, or 2FA requirement was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_REALM_INVALID", "message": "bot.realm must be \"global\" or a realm this computer belongs to (and the request realm on a realm URL)"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
BOT_REALM_INVALID | Bot realm not allowed | bot.realm must be global or a realm the destination computer belongs to. On a realm URL, it must be that realm. | Send the realm the agent reports for this Bot, from a URL that allows it. |
SERVER_BOT_URL_LIMIT | Server Bot URL limit reached | The server hosting the computer already has its maximum number of attached Bot URLs. The response carries data: {field: "server_bot_url_limit", server_id, max, used}. | Delete or re-point a Bot URL on that server. |
OTP_REQUIRED | 2FA verification required | An unused otp_code is required only when the account has 2FA enabled and requires it for API keys. | Provide an unused otp_code with a valid TOTP code or backup code. |
UPGRADE_REQUIRED | Request uses a retired name | The request uses a retired API name or comes from a Hoody CLI too old for the current API. Nothing was changed. | Send the replacement listed in data.renamed, or update the Hoody CLI and SDK. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The Bot URL or destination computer was not found.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist, or you do not have permission to access it. | Verify the computer id is correct and that you have access to the project it belongs to. |
The Bot URL is frozen, the destination Bot already has a URL, or the computer cannot be changed.
Media type: application/json
{ "statusCode": 409, "error": "BOT_URL_FROZEN", "message": "This Bot URL is frozen by an administrator"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_FROZEN | Bot URL frozen | An administrator froze this Bot URL. It cannot be turned on or re-pointed. | Contact support. |
BOT_URL_EXISTS | Bot already has a URL | Each Bot has at most one Bot URL. It can carry many named keys. | Use the existing Bot URL, add a key to it, or re-point it. |
BOT_FIELD_INVALID | Computer cannot hold a Bot URL | The destination computer cannot hold a Bot URL in its current state because it failed, is being deleted, was deleted, or is not yet placed on a server. data.field is computer_id. | Choose a computer that is placed on a server and is not failed or deleted, or retry once it is placed. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
TWOFACTOR_RATE_LIMIT | 2FA verification locked | Too many failed 2FA codes. 2FA checks are refused for up to 15 minutes; data.lockout_seconds says how long is left. | Wait data.lockout_seconds seconds, then try again with a current code. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Bot URLs are unavailable.
Media type: application/json
{ "statusCode": 503, "error": "BOTS_DISABLED", "message": "Bot URLs are not available right now"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOTS_DISABLED | Bot URLs unavailable | Bot URLs are switched off on this platform, or its Bot URL domain is not set up. Creating, turning on, re-pointing, and suggesting a name are refused. Reads, settings, delete, keys, and panic still work. While the domain is not set up, url, test_curl, connect, and the key curl lines are null. | Retry later. |
POST /api/v1/bot-urls/{id}/panic
Section titled “POST /api/v1/bot-urls/{id}/panic”Turns the URL off and revokes every key in one step. Callers are refused once the change is applied. Work the Bot already started keeps running, so stop it in the agent. Panic remains available while Bot URLs are switched off or their domain is not set up.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/panic' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.panic('bu_0123456789abcdef01234567');Response
Section titled “Response”The Bot URL was turned off and its keys were revoked.
Media type: application/json
{ "statusCode": 200, "message": "Bot URL turned off and every key revoked", "data": { "id": "bu_0123456789abcdef01234567", "label": "amber-falcon-river-k7m2q", "url": "https://amber-falcon-river-k7m2q.hoody.bot", "realm": "global", "project_id": "67e89abc123def456789abcd", "computer_id": "890abcdef12345678901cdef", "server_id": "67e89abc123def456789abcd", "bot": { "realm": "global", "id": "support-bot", "uid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f" }, "owner_enabled": false, "cors": true, "iframable": false, "limits": { "key_rpm": 60, "bot_rpm": 120, "key_concurrency": 4, "bot_concurrency": 8 }, "status": "disabled", "status_reason": "owner_disabled", "frozen": null, "revision": 10, "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": [], "created_at": "2026-04-12T10:14:23Z", "updated_at": "2026-05-03T18:30:00Z" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 10, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
The request body is not valid JSON.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
DELETE /api/v1/bot-urls/{id}
Section titled “DELETE /api/v1/bot-urls/{id}”Removes the URL. Its label stays taken forever and can never be used again by anyone. The reply carries the removal’s propagation, its only snapshot. GET /api/v1/bot-urls/{id} answers 404 BOT_URL_NOT_FOUND right away, and that 404 does not mean the removal is applied.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
curl -X DELETE 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.delete('bu_0123456789abcdef01234567');Response
Section titled “Response”The Bot URL was removed.
Media type: application/json
{ "statusCode": 200, "message": "Bot URL deleted", "data": { "id": "bu_0123456789abcdef01234567", "state": "removed" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 11, "action": "delete", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
The request body is not valid JSON.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Manage keys
Section titled “Manage keys”POST /api/v1/bot-urls/{id}/keys
Section titled “POST /api/v1/bot-urls/{id}/keys”Creates a named caller key on the Bot URL. The key’s secret is returned only in this response and cannot be read again, so store it when the response arrives. A Bot URL holds at most 20 live keys.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 32 characters: letters, digits, space, dot, underscore, and hyphen. Shown to the Bot as the caller name. |
ipv4_allow | array | No | IPv4 addresses or CIDRs allowed to use the key. Empty means any IPv4. At most 32 entries. |
expires_at | string | No | UTC time after which the key stops working, such as 2026-12-31T23:59:59Z. null means never. |
notes | string | No | Owner-only notes, at most 500 characters. Never shown to callers. |
holder_note | string | No | Note for whoever holds the key, at most 1000 characters. Plain text: line breaks are kept, control and invisible formatting characters are removed, and nothing is turned into a link. Returned by GET /v1/key. Empty, null, or a note with nothing visible left clears it. |
otp_code | string | No | Current 2FA code or backup code. Required only when your account has 2FA enabled and requires it for API keys. An unused code is required, and a code already used is refused. |
{ "name": "support-team", "ipv4_allow": [ "203.0.113.0/24", "198.51.100.7" ], "expires_at": "2026-12-31T23:59:59Z", "notes": "Issued for the front-line support team; expires are managed manually."}curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "name": "support-team", "ipv4_allow": ["203.0.113.0/24", "198.51.100.7"], "expires_at": "2026-12-31T23:59:59Z", "notes": "Issued for the front-line support team; expires are managed manually." }'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const { data: { secret } } = await client.api.botUrls.keys.create('bu_0123456789abcdef01234567', { name: 'support-team', ipv4_allow: ['203.0.113.0/24', '198.51.100.7'], expires_at: '2026-12-31T23:59:59Z', notes: 'Issued for the front-line support team; expires are managed manually.',});Response
Section titled “Response”The key was created. Its secret is included only in this response.
Media type: application/json
{ "statusCode": 201, "message": "Key created; the secret is shown only now", "data": { "key": { "id": "bk_89abcdef0123456789abcdef", "name": "support-team", "prefix": "hbk_4f9a2c1e", "enabled": true, "ipv4_allow": [ "203.0.113.0/24", "198.51.100.7" ], "expires_at": "2026-12-31T23:59:59Z", "notes": "Issued for the front-line support team; expires are managed manually.", "holder_note": null, "status": "active", "created_at": "2026-04-12T10:14:23Z", "rotated_at": null }, "secret": "hbk_4f9a2c1e…", "curl": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/models -H \"Authorization: Bearer hbk_4f9a2c1e…\"", "curl_chat": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/chat/completions -H \"Authorization: Bearer hbk_4f9a2c1e…\" -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_4f9a2c1e…\" -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 2, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A field, IPv4 allowlist, key count, or 2FA requirement was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_FIELD_INVALID", "message": "name must be string", "data": { "field": "name" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
BOT_IPV4_INVALID | Invalid IPv4 allowlist | Entries must be IPv4 addresses or CIDRs written canonically, with no leading zeros or host bits set. IPv6 is not supported. At most 32 entries. | Fix the entry. |
BOT_KEY_LIMIT | Too many keys | A Bot URL holds at most 20 live keys. The response carries data: {max, used}. | Revoke a key first. |
OTP_REQUIRED | 2FA verification required | An unused otp_code is required only when the account has 2FA enabled and requires it for API keys. | Provide an unused otp_code with a valid TOTP code or backup code. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
The key name is already used, or the computer cannot be changed.
Media type: application/json
{ "statusCode": 409, "error": "BOT_KEY_NAME_TAKEN", "message": "A key with this name already exists on this Bot URL"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_KEY_NAME_TAKEN | Key name taken | Key names are unique per Bot URL, ignoring case. | Choose another name. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
TWOFACTOR_RATE_LIMIT | 2FA verification locked | Too many failed 2FA codes. 2FA checks are refused for up to 15 minutes; data.lockout_seconds says how long is left. | Wait data.lockout_seconds seconds, then try again with a current code. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
POST /api/v1/bot-urls/{id}/keys/{keyId}/rotate
Section titled “POST /api/v1/bot-urls/{id}/keys/{keyId}/rotate”Replaces a key’s secret with a new one. The key id and settings are preserved. The old secret stops working once the change is applied. The new secret is included only in this response.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
keyId | path | string | Yes | Key id (bk_…) |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
otp_code | string | No | Current 2FA code or backup code. Required only when your account has 2FA enabled and requires it for API keys. An unused code is required, and a code already used is refused. |
{}curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/bk_89abcdef0123456789abcdef/rotate' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{}'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const { data: { secret } } = await client.api.botUrls.keys.rotate( 'bu_0123456789abcdef01234567', 'bk_89abcdef0123456789abcdef', {},);Response
Section titled “Response”The key was rotated. Its new secret is included only in this response.
Media type: application/json
{ "statusCode": 200, "message": "Key rotated; the new secret is shown only now", "data": { "key": { "id": "bk_89abcdef0123456789abcdef", "name": "support-team", "prefix": "hbk_8e2f1b6d", "enabled": true, "ipv4_allow": [ "203.0.113.0/24", "198.51.100.7" ], "expires_at": "2026-12-31T23:59:59Z", "notes": "Issued for the front-line support team; expires are managed manually.", "holder_note": null, "status": "active", "created_at": "2026-04-12T10:14:23Z", "rotated_at": "2026-05-10T09:00:00Z" }, "secret": "hbk_8e2f1b6d…", "curl": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/models -H \"Authorization: Bearer hbk_8e2f1b6d…\"", "curl_chat": "curl -sS https://amber-falcon-river-k7m2q.hoody.bot/v1/chat/completions -H \"Authorization: Bearer hbk_8e2f1b6d…\" -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_8e2f1b6d…\" -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 12, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A field or 2FA requirement was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_FIELD_INVALID", "message": "body must NOT have additional properties", "data": { "field": "body" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
OTP_REQUIRED | 2FA verification required | An unused otp_code is required only when the account has 2FA enabled and requires it for API keys. | Provide an unused otp_code with a valid TOTP code or backup code. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The Bot URL or key was not found.
Media type: application/json
{ "statusCode": 404, "error": "BOT_KEY_NOT_FOUND", "message": "Key not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
BOT_KEY_NOT_FOUND | Key not found | No live key with this id on this Bot URL. Revoked keys are gone for good. | Check the key id. |
The computer cannot be changed.
Media type: application/json
{ "statusCode": 409, "error": "SUBSERVER_DORMANT", "message": "This subserver is not active: its subscription is on hold, being delivered, or a change to it is in progress. Try again once it is active.", "data": { "server_id": "66f0a1b2c3d4e5f6a7b8c9d0", "reason": "not_active" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
TWOFACTOR_RATE_LIMIT | 2FA verification locked | Too many failed 2FA codes. 2FA checks are refused for up to 15 minutes; data.lockout_seconds says how long is left. | Wait data.lockout_seconds seconds, then try again with a current code. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
PATCH /api/v1/bot-urls/{id}/keys/{keyId}
Section titled “PATCH /api/v1/bot-urls/{id}/keys/{keyId}”Renames a key, pauses it with enabled: false, resumes it, or changes its IPv4 allowlist, expiry, owner notes, or holder note. The secret does not change. Use rotate to replace it.
Resuming, changing the allowlist, or changing the expiry needs otp_code when your account requires 2FA for API keys. Renaming, pausing, and changing notes do not.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
keyId | path | string | Yes | Key id (bk_…) |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | 1 to 32 characters: letters, digits, space, dot, underscore, and hyphen. Unique per Bot URL, ignoring case. |
ipv4_allow | array | No | IPv4 addresses or CIDRs allowed to use the key. Empty means any IPv4. At most 32 entries. |
expires_at | string | No | UTC time after which the key stops working. null means never. |
notes | string | No | Owner-only notes, at most 500 characters. null clears the notes. |
holder_note | string | No | Note for whoever holds the key, at most 1000 characters. Plain text: line breaks are kept, control and invisible formatting characters are removed, and nothing is turned into a link. Returned by GET /v1/key. Empty, null, or a note with nothing visible left clears it. |
enabled | boolean | No | Pause the key with false, or resume it with true |
otp_code | string | No | Current 2FA code or backup code. Required only when your account has 2FA enabled and requires it for API keys. An unused code is required, and a code already used is refused. |
{ "name": "support-team-2", "enabled": false, "ipv4_allow": [ "198.51.100.7" ], "expires_at": null, "notes": null}curl -X PATCH 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/bk_89abcdef0123456789abcdef' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "enabled": false }'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.keys.update('bu_0123456789abcdef01234567', 'bk_89abcdef0123456789abcdef', { enabled: false,});Response
Section titled “Response”The key was changed.
Media type: application/json
{ "statusCode": 200, "message": "Key updated", "data": { "id": "bk_89abcdef0123456789abcdef", "name": "support-team-2", "prefix": "hbk_4f9a2c1e", "enabled": false, "ipv4_allow": [ "198.51.100.7" ], "expires_at": null, "notes": null, "holder_note": null, "status": "paused", "created_at": "2026-04-12T10:14:23Z", "rotated_at": null }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 13, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}A field, IPv4 allowlist, or 2FA requirement was not accepted.
Media type: application/json
{ "statusCode": 400, "error": "BOT_FIELD_INVALID", "message": "enabled must be boolean", "data": { "field": "enabled" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_FIELD_INVALID | Invalid field | A field failed validation, has the wrong type, or the body, bot, or limits has an unknown field. data.field names it. Nothing is coerced or dropped. | Fix the field. |
BOT_IPV4_INVALID | Invalid IPv4 allowlist | Entries must be IPv4 addresses or CIDRs written canonically, with no leading zeros or host bits set. IPv6 is not supported. At most 32 entries. | Fix the entry. |
OTP_REQUIRED | 2FA verification required | An unused otp_code is required only when the account has 2FA enabled and requires it for API keys. | Provide an unused otp_code with a valid TOTP code or backup code. |
The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The Bot URL or key was not found.
Media type: application/json
{ "statusCode": 404, "error": "BOT_KEY_NOT_FOUND", "message": "Key not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
BOT_KEY_NOT_FOUND | Key not found | No live key with this id on this Bot URL. Revoked keys are gone for good. | Check the key id. |
The key name is already used, or the computer cannot be changed.
Media type: application/json
{ "statusCode": 409, "error": "BOT_KEY_NAME_TAKEN", "message": "A key with this name already exists on this Bot URL"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_KEY_NAME_TAKEN | Key name taken | Key names are unique per Bot URL, ignoring case. | Choose another name. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. |
The JSON body could not be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
TWOFACTOR_RATE_LIMIT | 2FA verification locked | Too many failed 2FA codes. 2FA checks are refused for up to 15 minutes; data.lockout_seconds says how long is left. | Wait data.lockout_seconds seconds, then try again with a current code. |
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
DELETE /api/v1/bot-urls/{id}/keys/{keyId}
Section titled “DELETE /api/v1/bot-urls/{id}/keys/{keyId}”Permanently revokes one key. The Bot URL itself stays on, and only this key stops working. Revoke is final, so the key id cannot be reused.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
keyId | path | string | Yes | Key id (bk_…) |
curl -X DELETE 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/bk_89abcdef0123456789abcdef' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.keys.revoke('bu_0123456789abcdef01234567', 'bk_89abcdef0123456789abcdef');Response
Section titled “Response”The key was revoked.
Media type: application/json
{ "statusCode": 200, "message": "Key revoked", "data": { "id": "bk_89abcdef0123456789abcdef", "status": "revoked" }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 14, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The Bot URL or key was not found.
Media type: application/json
{ "statusCode": 404, "error": "BOT_KEY_NOT_FOUND", "message": "Key not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
BOT_KEY_NOT_FOUND | Key not found | No live key with this id on this Bot URL. Revoked keys are gone for good. | Check the key id. |
The request body is not valid JSON.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
POST /api/v1/bot-urls/{id}/keys/revoke-all
Section titled “POST /api/v1/bot-urls/{id}/keys/revoke-all”Permanently revokes every key of the Bot URL in one call. The URL itself stays on. Pair this operation with panic if you also want to turn the URL off.
The project owner or an administrator may call this endpoint. Project members are refused, and auth tokens need resources.bot_urls.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Bot URL id (bu_…) |
curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/revoke-all' \ -H 'Authorization: Bearer <token>'SDK usage
Section titled “SDK usage”import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.botUrls.keys.revokeAll('bu_0123456789abcdef01234567');Response
Section titled “Response”Every key was revoked.
Media type: application/json
{ "statusCode": 200, "message": "Every key revoked", "data": { "revoked_count": 3 }, "propagation": { "committed": true, "complete": false, "state": "pending", "generation": 15, "action": "upsert", "succeeded_count": 2, "failed_count": 0, "pending_count": 1, "target_count": 3, "deny_targets": [] }}The request did not include valid, current credentials.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token | Send an Authorization header as Bearer <token> with a sign-in token or an auth token |
INVALID_TOKEN | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
TOKEN_EXPIRED | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token or one above it has been revoked, disabled, or has expired, so this one no longer authenticates | Create a new auth token from a valid one, or sign in again |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect | Verify your credentials and try again, or use the password reset feature |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend-verification action without asking again. | Complete email verification through the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also verifies the email |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The credentials do not allow this operation.
Media type: application/json
{ "statusCode": 403, "error": "BOT_URL_OWNER_ONLY", "message": "Only the project owner can manage Bot URLs. Ask the project owner."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_OWNER_ONLY | Project owner only | Only the project owner can manage Bot URLs. Project members cannot. | Ask the project owner. |
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
No Bot URL with this id is available to the caller.
Media type: application/json
{ "statusCode": 404, "error": "BOT_URL_NOT_FOUND", "message": "Bot URL not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BOT_URL_NOT_FOUND | Bot URL not found | No Bot URL with this id that the caller owns. | Check the id. |
The request body is not valid JSON.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Invalid JSON in request body"}The request was rate limited.
Media type: application/json
{ "statusCode": 429, "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded for this endpoint. Please try again later.", "data": {}}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |