Skip to content

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

Hoody.com

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:

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.

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.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/bot-urls/suggest-label' \
-H 'Authorization: Bearer <token>'

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"
}
}

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.

NameInTypeRequiredDescription
project_idquerystringNoFilter to one project id
computer_idquerystringNoFilter to one computer id
limitqueryintegerNoBot URLs per page, from 1 to 100. Default: 50
cursorquerystringNoThe next_cursor returned by the previous page
Terminal window
curl -X GET 'https://api.hoody.com/api/v1/bot-urls?limit=25' \
-H 'Authorization: Bearer <token>'

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
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
Terminal window
curl -X GET 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567' \
-H 'Authorization: Bearer <token>'

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": []
}
}

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.

FieldTypeRequiredDescription
computer_idstringYesId of the computer hosting the agent Bot
botobjectYesThe agent Bot the URL serves
bot.realmstringYesglobal or a realm of the destination computer
bot.idstringYesBot id, up to 64 characters
bot.uidstringYesBot UID, up to 36 characters
labelstringNo8 to 48 characters, lowercase letters, digits, and single hyphens. Starts with a letter and ends with a letter or digit.
corsbooleanNoAllow browser calls. Default: true
iframablebooleanNoOnly false is accepted here. Default: false. Turn it on after creation by changing the Bot URL.
limitsobjectNoRequest limits
limits.key_rpmintegerNoPer-key requests per minute, from 1 to 600. Default: 60
limits.bot_rpmintegerNoPer-Bot requests per minute, from 1 to 3000. Default: 120
limits.key_concurrencyintegerNoPer-key concurrent calls, from 1 to 16. Default: 4
limits.bot_concurrencyintegerNoPer-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
}
}
Terminal window
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
}
}'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
FieldTypeRequiredDescription
enabledbooleanNoThe owner switch. true turns the URL on, and false turns it off.
corsbooleanNoAllow or refuse browser calls
iframablebooleanNoAllow or refuse other websites to show the Bot page in a frame
limitsobjectNoNew request limits
limits.key_rpmintegerNoPer-key requests per minute, from 1 to 600. Default: 60
limits.bot_rpmintegerNoPer-Bot requests per minute, from 1 to 3000. Default: 120
limits.key_concurrencyintegerNoPer-key concurrent calls, from 1 to 16. Default: 4
limits.bot_concurrencyintegerNoPer-Bot concurrent calls, from 1 to 32. Default: 8
otp_codestringNoCurrent 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
}
}
Terminal window
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 }'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
FieldTypeRequiredDescription
computer_idstringYesId of the destination computer
botobjectYesThe agent Bot now served by the URL
bot.realmstringYesglobal or a realm of the destination computer
bot.idstringYesBot id, up to 64 characters
bot.uidstringYesBot UID, up to 36 characters
otp_codestringNoCurrent 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"
}
}
Terminal window
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"
}
}'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
Terminal window
curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/panic' \
-H 'Authorization: Bearer <token>'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
Terminal window
curl -X DELETE 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567' \
-H 'Authorization: Bearer <token>'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
FieldTypeRequiredDescription
namestringYes1 to 32 characters: letters, digits, space, dot, underscore, and hyphen. Shown to the Bot as the caller name.
ipv4_allowarrayNoIPv4 addresses or CIDRs allowed to use the key. Empty means any IPv4. At most 32 entries.
expires_atstringNoUTC time after which the key stops working, such as 2026-12-31T23:59:59Z. null means never.
notesstringNoOwner-only notes, at most 500 characters. Never shown to callers.
holder_notestringNoNote 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_codestringNoCurrent 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."
}
Terminal window
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."
}'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
keyIdpathstringYesKey id (bk_…)
FieldTypeRequiredDescription
otp_codestringNoCurrent 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.
{}
Terminal window
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 '{}'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
keyIdpathstringYesKey id (bk_…)
FieldTypeRequiredDescription
namestringNo1 to 32 characters: letters, digits, space, dot, underscore, and hyphen. Unique per Bot URL, ignoring case.
ipv4_allowarrayNoIPv4 addresses or CIDRs allowed to use the key. Empty means any IPv4. At most 32 entries.
expires_atstringNoUTC time after which the key stops working. null means never.
notesstringNoOwner-only notes, at most 500 characters. null clears the notes.
holder_notestringNoNote 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.
enabledbooleanNoPause the key with false, or resume it with true
otp_codestringNoCurrent 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
}
Terminal window
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 }'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
keyIdpathstringYesKey id (bk_…)
Terminal window
curl -X DELETE 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/bk_89abcdef0123456789abcdef' \
-H 'Authorization: Bearer <token>'

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": []
}
}

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.

NameInTypeRequiredDescription
idpathstringYesBot URL id (bu_…)
Terminal window
curl -X POST 'https://api.hoody.com/api/v1/bot-urls/bu_0123456789abcdef01234567/keys/revoke-all' \
-H 'Authorization: Bearer <token>'

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": []
}
}