Agent: Bots
Section titled “Agent: Bots”A Bot is a long-lived assistant of the Hoody Agent. It opens delegate sessions on computers and agents, follows them, and reports what they did. Use these endpoints to create and manage Bots, post messages, follow their logs, replace guardrails, answer their gates, and stop their delegates.
The default Bot, chief, is created on first use. In the Hub, open Bots and choose New Bot. Choose a running computer and fill in the Bot’s settings. Select an existing Bot to send it messages, follow its work, or open its Settings.
A typical flow is to create a Bot or use chief, post a message, follow the reply, and stop a delegate when it is no longer needed. Posting a message returns 202, and the reply arrives on the Bot’s stream and in its log.
All endpoints use this computer URL:
https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com
All routes are under /api/v1/agent/bots. Who may call a route is determined by the computer’s proxy permission rules.
For delegate sessions, see Agent sessions. Voice, chat channels, Bot URLs, and the OpenAI- and Anthropic-compatible APIs are documented separately in Bot voice, Bot channels, and Bot URLs.
Shared response models
Section titled “Shared response models”Bot resource
Section titled “Bot resource”Endpoints that return a Bot use the following fields. GET /api/v1/agent/bots/{id} also returns speech_usage and urls. PATCH /api/v1/agent/bots/{id} also returns model_applies.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The Bot id, unique within its realm and fixed at creation. |
uid | string | Yes | The globally unique Bot id, fixed at creation. |
realm | string | Yes | The Bot’s realm, either global or a realm id. |
address | string | Yes | The Bot’s address in messages and logs, in the form bot:<realm>/<id>. |
name | string | Yes | Display name. |
role | string | Yes | What the Bot is for. Empty when unset. |
instructions | string | Yes | Instructions about tone or format. They do not override rules or guardrails and are not passed to delegates. |
session_id | string | Yes | The Bot’s own session. Empty until its first message is posted. |
model | string | Yes | Model selected for the Bot’s session. Empty means the bot agent’s own model. |
session_model | string | No | Model reported by the current session. It can differ from model until the Bot is reset. |
guardrails | string | Yes | Limits that apply to the Bot and every delegate it opens. |
allowed_computers | array | Yes | Computers on which the Bot may open delegates. Empty means any. |
allowed_agents | array | Yes | Agents with which the Bot may open delegates. Empty means any. |
yolo | boolean | Yes | Whether every delegate runs with tool approvals granted automatically. |
guardrail_check | string | Yes | Guardrail check mode: strict, lenient, or off. |
async | boolean | Yes | Whether compatible API answers return before delegates show their first step. Default: false. |
wait_seconds | integer | Yes | Compatible API wait time for delegates, from 1 to 60. Default: 15. |
mcp_hints | boolean | Yes | Whether MCP results end with counts of new messages and approvals. Default: true. |
routing | object | Yes | Routing configuration. It can be null. |
routing.mode | string | Yes | Routing mode: off, suggest, or auto. |
routing.light | object | No | Worker for tasks without a heavy trait. Required unless routing is off. |
routing.light.model | string | Yes | Model for the light worker. |
routing.light.thinking | string | No | Thinking setting: empty, off, on, low, medium, high, xhigh, or max. |
routing.heavy | object | No | Worker for tasks with a heavy trait. Required unless routing is off. |
routing.heavy.model | string | Yes | Model for the heavy worker. |
routing.heavy.thinking | string | No | Thinking setting: empty, off, on, low, medium, high, xhigh, or max. |
worker_backend | string | Yes | Default delegate backend: llm or acp. |
worker_delegated_agent | string | Yes | Delegated agent for an acp worker, such as claude. Empty when unset. |
allowed_worker_backends | array | Yes | Backends a dispatch may name. |
worker_delegated_model | string | Yes | Claude model for an acp delegate. Empty means the configured or default model. |
worker_delegated_effort | string | Yes | Effort for an acp delegate: low, medium, high, xhigh, or max. Empty means its own default. |
worker_model | string | Yes | Model for an llm delegate when no routing tier applies. Empty means the agent’s model. |
worker_thinking | string | Yes | Thinking setting for worker_model. Empty means the model’s default. |
speech | object | Yes | Speech settings. It can be null. |
speech.tts_model | string | No | Text-to-speech model. |
speech.stt_model | string | No | Speech-to-text model. Empty means the agent’s default. |
speech.voice | string | No | Voice for tts_model. |
speech.language | string | No | Speech language, such as en or auto. |
speech.speed | number | No | Speaking speed for tts_model. |
speech.stt_prompt | string | No | Words expected by the speech-to-text model. Maximum length: 500. |
speech.speak_wakes | boolean | No | Whether delegate reports are spoken. Default: false. |
speech.speak_gates | boolean | No | Whether waiting approvals and questions are announced. Default: true. |
speech.limits | object | No | The Bot’s daily speech limits. |
speech.limits.tts_chars | integer | No | Characters read aloud per UTC day. 0 disables speech output. |
speech.limits.stt_seconds | integer | No | Seconds transcribed per UTC day. 0 disables spoken messages. |
yolo_unapplied | array | Yes | Open delegates whose approval mode does not yet match yolo. |
yolo_unapplied[].session_id | string | Yes | Delegate session id. |
yolo_unapplied[].state | string | Yes | pending or refused. |
yolo_unapplied[].reason | string | No | Why the last attempt did not apply. |
created | string | Yes | Creation time in RFC 3339 format. |
created_by | object | Yes | Creator record. It grants no access. |
created_by.kind | string | Yes | user, api, or system. |
created_by.id | string | No | Creator id, when known. |
revision | integer | Yes | Settings revision. It increases after settings or guardrails are written. |
autonomy | object | Yes | Limits and usage for work the Bot starts without a new user message. |
autonomy.used | integer | Yes | Autonomous actions used since your last message. |
autonomy.max | integer | Yes | Maximum autonomous actions between user messages. |
autonomy.per_delegate_max | integer | Yes | Maximum autonomous actions sent to one delegate. |
autonomy.waiting_for_you | boolean | Yes | Whether the Bot has reached an autonomy limit. |
realtime_items | object | Yes | Realtime item usage and limit. |
realtime_items.used | integer | Yes | Realtime items seen. It can be null when they cannot be read. |
realtime_items.max | integer | Yes | Maximum Realtime items the Bot can record. |
open_delegates | integer | Yes | Number of open delegate sessions. |
queued | integer | Yes | Messages and delegate events waiting to be posted. |
turn_running | boolean | Yes | Whether the Bot is working on a turn. |
turn_id | string | No | Running turn id, present while turn_running is true. |
pending_gate | object | Yes | Approval or question parked on the Bot’s own session. It can be null. |
pending_gate.session_id | string | Yes | Bot session holding the gate. |
pending_gate.gate_id | string | Yes | Answerable gate id. |
pending_gate.type | string | Yes | confirm or question. |
pending_gate.summary | string | Yes | One-line summary of what the gate asks. |
pending_gate.generation | integer | Yes | Gate generation to echo when answering. |
channels | array | Yes | Summary of the Bot’s chat channels. |
channels[].id | string | Yes | Channel id. |
channels[].kind | string | Yes | discord, slack, or telegram. |
channels[].label | string | Yes | Your label for the channel. |
channels[].state | string | Yes | Channel connection state: connecting, connected, awaiting_owner, degraded, standby, conflict, auth_failed, paused, realm_unserved, stopping, or stopped. |
channels[].state_reason | string | No | Reason for the current channel state. |
channels[].paired_count | integer | Yes | Number of paired people. |
channels[].requested_chats | integer | Yes | Chats waiting for approval. |
channels[].notes | array | Yes | Notes from the last credential check. |
channels[].notes[].code | string | Yes | Note code. |
channels[].notes[].field | string | Yes | Setting the note concerns. |
channels[].notes[].reason | string | No | Reason for the note. |
speech_usage | object | No | Current speech usage and limits. Absent when usage cannot be read. |
speech_usage.day | string | Yes | UTC usage date in YYYY-MM-DD format. |
speech_usage.resets_at | string | Yes | Next UTC reset time in RFC 3339 format. |
speech_usage.tts_chars | number | Yes | Characters read aloud today. |
speech_usage.stt_seconds | number | Yes | Seconds transcribed today. |
speech_usage.limits | object | Yes | The Bot’s effective daily limits. |
speech_usage.limits.tts_chars | integer | No | Daily character limit. |
speech_usage.limits.stt_seconds | integer | No | Daily transcription limit. |
speech_usage.limits.source | object | No | Source of each limit, bot or default. |
speech_usage.limits.source.tts_chars | string | No | Character limit source. |
speech_usage.limits.source.stt_seconds | string | No | Transcription limit source. |
speech_usage.realm_used | object | Yes | Realm-wide speech usage today. |
speech_usage.realm_used.tts_chars | number | No | Realm characters read aloud today. |
speech_usage.realm_used.stt_seconds | number | No | Realm seconds transcribed today. |
speech_usage.realm_limits | object | Yes | Realm-wide daily limits. |
speech_usage.realm_limits.tts_chars | integer | No | Realm daily character limit. |
speech_usage.realm_limits.stt_seconds | integer | No | Realm daily transcription limit. |
urls | object | Yes | Compatible client URLs for the Bot. |
urls.openai | string | Yes | OpenAI-compatible base URL. |
urls.anthropic | string | Yes | Anthropic-compatible base URL. |
urls.mcp | string | Yes | MCP Streamable HTTP URL. |
model_applies | string | Yes | When model takes effect: after_reset or next_session. |
Bot list response
Section titled “Bot list response”| Name | Type | Required | Description |
|---|---|---|---|
items | array | Yes | The Bots in the selected realm. A Bot served by another agent process appears as a locked row. |
meta | object | Yes | Pagination metadata. |
meta.total | integer | No | Total number of Bots across all pages. |
meta.page | integer | No | One-based page number, present when limit is greater than 0. |
meta.limit | integer | No | Items per page, present when limit is greater than 0. |
suspended_count | integer | Yes | Number of suspended Bots that are not listed. |
A locked list row has only id, realm, address, and owned_elsewhere. The owned_elsewhere value is always true.
Log and archive response
Section titled “Log and archive response”Both log and archive endpoints return the same page structure. Archive rows are rows previously moved out of the active log.
| Name | Type | Required | Description |
|---|---|---|---|
items | array | Yes | Rows in sequence order. |
items[].seq | integer | Yes | Row position. It increases by one per row and survives forget. |
items[].at | string | Yes | Time the row was written in RFC 3339 format. |
items[].role | string | Yes | user, bot, event, or system. |
items[].text | string | Yes | Row text. |
items[].session_id | string | No | Bot or delegate session the row concerns. |
items[].turn_id | string | No | Bot turn ended by a reply row. |
items[].message_id | string | No | Accepted message id on a user row. |
items[].message_ids | array | No | Message ids answered by a reply or turn-result row. |
items[].from | object | No | Who wrote the row. |
items[].from.kind | string | Yes | user, bot, delegate, or system. |
items[].from.id | string | No | Sender id within the kind. |
items[].trigger | string | No | human, wake, or clear. |
items[].sender | object | No | Door through which a user message arrived. |
items[].sender.via | string | No | Door name. |
items[].schema_version | integer | No | Row format version. |
items[].kind | string | No | Runtime row kind: budget, channel, error, gate, gone, limit, not_sent, note, provider, realtime, report, reset, route, stop, or waiter. |
items[].fail_kind | string | No | Cause of a failed Bot turn: auth, bad_tool_args, content_filter, context_overflow, max_tokens, model, network, no_credentials, other, pause_turn, provider, provider_incomplete_response, quota_wait, rate_limit, refusal, spend_cap, timeout, unconfigured, or unexpected_stop. |
items[].delegate_title | string | No | Delegate title when the row was written. |
items[].voice | object | No | Voice-message metadata. |
items[].voice.origin | string | Yes | rest, mcp, ws, realtime, or twilio. |
items[].voice.duration_ms | integer | Yes | Audio duration in milliseconds. |
items[].voice.lang | string | No | Transcribed language. |
items[].voice.conn | string | No | Voice connection id. |
items[].voice.utt | integer | No | Voice connection utterance number. |
next_since | integer | Yes | Sequence to pass as since to read the next page. |
has_more | boolean | Yes | Whether another page is available. |
before | integer | No | Sequence to pass as before when reading backward. |
Delegate list response
Section titled “Delegate list response”| Name | Type | Required | Description |
|---|---|---|---|
items | array | Yes | Delegate sessions opened by the Bot. |
items[].session_id | string | Yes | Delegate session id. |
items[].computer | string | Yes | Computer on which the delegate runs. Empty for the agent’s own computer. |
items[].agent | string | Yes | Agent on which the delegate runs. Empty for the default agent. |
items[].title | string | Yes | Title given by the Bot. |
items[].model | string | Yes | Model reported by the delegate session. |
items[].backend | string | Yes | llm or acp. |
items[].delegated_agent | string | Yes | Delegated agent for an acp delegate. Empty otherwise. |
items[].state | string | Yes | open or closed. |
items[].opened_at | string | Yes | Opening time in RFC 3339 format. |
items[].close_reason | string | No | Why a closed delegate ended. |
items[].last_turn_id | string | Yes | Last delegate turn known to the Bot. |
items[].route | object | Yes | Routing decision for the dispatch. It can be null. |
items[].route.mode | string | Yes | suggest or auto. |
items[].route.applied | boolean | Yes | Whether the selected worker was applied. |
items[].route.worker | string | No | light or heavy. |
items[].route.model | string | No | Selected worker model. |
items[].route.thinking | string | No | Selected worker thinking setting. |
items[].route.routed_by | string | Yes | jev, explicit, length, or fallback. |
items[].route.reason | string | Yes | Why the route was selected. |
items[].route.traits | object | No | Trait probabilities returned by the routing checker. |
items[].route.judge | string | No | Routing checker model. |
items[].route.policy | string | Yes | Routing policy version. |
items[].capability | string | No | next_step, turn_end, or unsupported. |
items[].current_step | object | No | Current coarse activity of an open delegate. |
items[].current_step.kind | string | Yes | model, tool, gate, or idle. |
items[].current_step.tool | string | No | Tool currently running. |
items[].current_step.since | string | Yes | Time the current step began. |
items[].open_gates | array | Yes | Approvals and questions the delegate is waiting on. |
items[].open_gates[].gate_id | string | Yes | Answerable gate id. |
items[].open_gates[].type | string | Yes | confirm or question. |
items[].open_gates[].summary | string | Yes | One-line summary. |
items[].open_gates[].generation | integer | Yes | Gate generation. |
items[].queued_commands | integer | No | Bot messages the delegate has not read. |
items[].last_command | object | No | Last message or stop sent to the delegate. |
items[].last_command.command_id | string | No | Delegate session command id. |
items[].last_command.kind | string | Yes | message, interrupt, or stop. |
items[].last_command.state | string | Yes | sending, queued, committed, superseded, refused, or failed. |
items[].last_command.how | string | No | next_step, new_turn, or stop. |
items[].last_command.from | string | Yes | bot or user. |
items[].last_command.at | string | Yes | Time the command was sent. |
items[].last_command.reason | string | No | Why a command was superseded, refused, or failed. |
meta | object | Yes | Pagination metadata. |
meta.total | integer | No | Total delegates across all pages. |
meta.page | integer | No | One-based page number. |
meta.limit | integer | No | Items per page. |
Error response body
Section titled “Error response body”JSON error responses use these fields:
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Structured error details when available. |
Create and read Bots
Section titled “Create and read Bots”POST /api/v1/agent/bots
Section titled “POST /api/v1/agent/bots”Creates a Bot. The Bot’s own session opens when its first message is posted.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Realm in which to create the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”All body fields are optional.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | No | Bot id matching ^[a-z0-9][a-z0-9_-]{0,63}$. If omitted, one is generated. |
name | string | No | Display name. If omitted, it defaults to id. |
role | string | No | What the Bot is for. Maximum length: 1000. |
instructions | string | No | Instructions about tone or format. Maximum length: 4000. |
model | string | No | Model for the Bot’s session. Empty means the bot agent’s own model. |
guardrails | string | No | Limits applied to the Bot and every delegate it opens. |
allowed_computers | array | No | Computers on which delegates may run. Empty or omitted means any. |
allowed_agents | array | No | Agents with which delegates may run. Empty or omitted means any. |
yolo | boolean | No | Whether every delegate receives automatic tool approvals. Default: false. |
guardrail_check | string | No | strict, lenient, or off. |
async | boolean | No | Whether compatible API answers return immediately. Default: false. |
wait_seconds | integer | No | From 1 to 60. Default: 15. |
mcp_hints | boolean | No | Whether MCP results include pending-message and approval counts. Default: true. |
routing | object | No | Routing configuration. It can be null. Default: off. |
routing.mode | string | No | off, suggest, or auto. Required within a routing object. |
routing.light | object | No | Light worker. Required unless routing is off. |
routing.light.model | string | No | Light worker model. Required within routing.light. |
routing.light.thinking | string | No | Light worker thinking setting. |
routing.heavy | object | No | Heavy worker. Required unless routing is off. |
routing.heavy.model | string | No | Heavy worker model. Required within routing.heavy. |
routing.heavy.thinking | string | No | Heavy worker thinking setting. |
worker_backend | string | No | llm, acp, or null. Default: llm. |
worker_delegated_agent | string | null | No | Delegated agent for an acp worker. It is required while acp is allowed. |
allowed_worker_backends | array | null | No | Backends a dispatch may name. If omitted, worker_backend alone applies. |
worker_delegated_model | string | null | No | Claude model for an acp delegate. |
worker_delegated_effort | string | No | low, medium, high, xhigh, max, or null. Empty uses Claude Code’s default. |
worker_model | string | null | No | Model for an llm delegate when no routing tier applies. |
worker_thinking | string | No | off, on, low, medium, high, xhigh, max, or null. |
speech | object | No | Speech settings. It can be null. |
The Bot’s name, role, instructions, guardrails, and dispatch limits must fit in 16 KiB. Speech limits default to 200000 characters and 14400 seconds per UTC day.
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots?realm=global" \ -H "Content-Type: application/json" \ -d '{ "id": "release-bot", "name": "Release Bot", "role": "Prepares and verifies the weekly release.", "instructions": "Answer in short bullet points.", "guardrails": "Never push to main." }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const bot = await client.agent.bots.create( { id: 'release-bot', name: 'Release Bot', role: 'Prepares and verifies the weekly release.', instructions: 'Answer in short bullet points.', guardrails: 'Never push to main.' }, { agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "address": "bot:global/release-bot", "allowed_agents": [], "allowed_computers": [], "allowed_worker_backends": [ "llm" ], "async": false, "autonomy": { "max": 10, "per_delegate_max": 3, "used": 0, "waiting_for_you": false }, "channels": [], "created": "2026-10-08T10:30:00Z", "created_by": { "kind": "api" }, "guardrail_check": "strict", "guardrails": "Never push to main.", "id": "release-bot", "instructions": "Answer in short bullet points.", "mcp_hints": true, "model": "", "name": "Release Bot", "open_delegates": 0, "pending_gate": null, "queued": 0, "realm": "global", "realtime_items": { "max": 1048576, "used": 0 }, "revision": 1, "role": "Prepares and verifies the weekly release.", "routing": null, "session_id": "", "speech": null, "turn_running": false, "uid": "0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c", "wait_seconds": 15, "worker_backend": "llm", "worker_delegated_agent": "", "worker_delegated_effort": "", "worker_delegated_model": "", "worker_model": "", "worker_thinking": "", "yolo": false, "yolo_unapplied": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid values. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector was not valid for this route or conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
upgrade_required | Renamed field | The request contains a field name that was renamed when Hoody computers replaced the old terminology. | Send the current field name from details.renamed. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested realm or resource does not exist. | Verify the realm and identifier. |
Media type: application/json
{ "code": "bot_exists", "message": "a Bot with this id already exists"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_exists | Bot exists | A Bot with this id already exists in the realm. | Choose another id or omit id to generate one. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "model_unavailable", "message": "unknown model \"nope/not-a-model\": a model spec starts with a provider prefix (for example hoody-ai/); list the available models with GET /api/v1/agent/models", "details": { "reason": "unknown_model" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The model cannot start a Bot session. details.reason can be unknown_model, non_chat_provider, speech_model, not_tts, not_stt, provider_refused, or not_claude. | Choose an available chat or speech model, or send an empty model to use the bot agent’s own model. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots
Section titled “GET /api/v1/agent/bots”Lists the Bots in a realm, sorted by id. The default Bot, chief, is created on first use, so the list is not empty. With ?realm=all, the list includes every realm the login serves, global included, and is sorted by realm and then id. Each row carries its realm and address.
A Bot served by another agent process appears as a locked row with owned_elsewhere: true.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | query | string | No | Realm to list: global, a 24-hex realm id, or all. all is accepted only here. |
page | query | integer | No | One-based page number. |
limit | query | integer | No | Maximum items per page. 0 disables pagination. |
X-Hoody-Realm | header | string | No | Realm to list: global or a 24-hex realm id. The header does not accept all. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots?realm=global&page=1&limit=20"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
for await (const bot of client.agent.bots.listIterator({ agentRealm: 'global' })) { console.log(bot.id);}Response
Section titled “Response”Media type: application/json
{ "items": [ { "address": "bot:global/chief", "allowed_agents": [], "allowed_computers": [], "allowed_worker_backends": [ "llm" ], "async": false, "autonomy": { "max": 10, "per_delegate_max": 3, "used": 0, "waiting_for_you": false }, "channels": [ { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "notes": [], "paired_count": 1, "requested_chats": 0, "state": "connecting" } ], "created": "2026-10-08T10:30:00Z", "created_by": { "kind": "system" }, "guardrail_check": "strict", "guardrails": "Never push to main.", "id": "chief", "instructions": "Answer in short bullet points.", "mcp_hints": true, "model": "", "name": "Chief", "open_delegates": 1, "pending_gate": null, "queued": 0, "realm": "global", "realtime_items": { "max": 1048576, "used": 0 }, "revision": 3, "role": "Keeps the web app's releases moving.", "routing": null, "session_id": "5f0c2a91d3b44e7f", "session_model": "hoody-ai/hoody-free", "speech": null, "turn_running": false, "uid": "0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c", "wait_seconds": 15, "worker_backend": "llm", "worker_delegated_agent": "", "worker_delegated_effort": "", "worker_delegated_model": "", "worker_model": "", "worker_thinking": "", "yolo": false, "yolo_unapplied": [] } ], "meta": { "total": 1 }, "suspended_count": 0}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid pagination values. | Correct the query parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. The query selector on this route can also be all. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The selected realm is not served by this login. | Select a realm served by the login. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots/{id}
Section titled “GET /api/v1/agent/bots/{id}”Returns one Bot. The chief Bot is created on first use.
The Bot’s live progress is on its own session. Follow session_id with GET /api/v1/agent/sessions/{id}/stream for reply text, thinking, tool calls, and turn completion. This Bot log stream carries only finished log rows.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief?realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const bot = await client.agent.bots.get('chief', { agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "address": "bot:global/chief", "allowed_agents": [], "allowed_computers": [], "allowed_worker_backends": [ "llm" ], "async": false, "autonomy": { "max": 10, "per_delegate_max": 3, "used": 0, "waiting_for_you": false }, "channels": [ { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "notes": [], "paired_count": 1, "requested_chats": 0, "state": "connecting" } ], "created": "2026-10-08T10:30:00Z", "created_by": { "kind": "system" }, "guardrail_check": "strict", "guardrails": "Never push to main.", "id": "chief", "instructions": "Answer in short bullet points.", "mcp_hints": true, "model": "", "name": "Chief", "open_delegates": 1, "pending_gate": null, "queued": 0, "realm": "global", "realtime_items": { "max": 1048576, "used": 0 }, "revision": 3, "role": "Keeps the web app's releases moving.", "routing": null, "session_id": "5f0c2a91d3b44e7f", "session_model": "hoody-ai/hoody-free", "speech": null, "turn_running": false, "uid": "0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c", "urls": { "anthropic": "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief", "mcp": "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp", "openai": "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/v1" }, "wait_seconds": 15, "worker_backend": "llm", "worker_delegated_agent": "", "worker_delegated_effort": "", "worker_delegated_model": "", "worker_model": "", "worker_thinking": "", "yolo": false, "yolo_unapplied": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
Change and remove Bots
Section titled “Change and remove Bots”PATCH /api/v1/agent/bots/{id}
Section titled “PATCH /api/v1/agent/bots/{id}”Changes the fields named in the request body. Omitted fields remain unchanged.
name, role, and instructions are announced before the Bot’s next message. yolo applies immediately to open delegates. allowed_computers, allowed_agents, routing, and worker settings apply to the next delegate. guardrail_check applies to the next dispatch or delegate message. async, wait_seconds, and mcp_hints apply to the next compatible API use. model applies to the next Bot session, so reset the Bot to start one with the new model.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents a change to a different Bot that now holds the same id. |
expect_revision | query | integer | No | The settings revision that was read. It prevents overwriting newer settings. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
name | string | No | Display name. |
role | string | No | What the Bot is for. Empty clears it. Maximum length: 1000. |
instructions | string | No | Instructions about tone or format. Empty clears them. Maximum length: 4000. |
model | string | No | Model for the Bot’s next session. Empty uses the bot agent’s own model. |
allowed_computers | array | No | Computers on which delegates may run. Empty means any. |
allowed_agents | array | No | Agents with which delegates may run. Empty means any. |
yolo | boolean | No | Approval mode for every delegate. |
guardrail_check | string | No | strict, lenient, or off. |
async | boolean | No | Whether compatible API answers return immediately. |
wait_seconds | integer | No | From 1 to 60. |
mcp_hints | boolean | No | Whether MCP results end with pending-message and approval counts. |
routing | object | No | Complete replacement routing configuration. It can be null. |
routing.mode | string | No | off, suggest, or auto. |
routing.light | object | No | Light worker configuration. |
routing.light.model | string | No | Light worker model. |
routing.light.thinking | string | No | Light worker thinking setting. |
routing.heavy | object | No | Heavy worker configuration. |
routing.heavy.model | string | No | Heavy worker model. |
routing.heavy.thinking | string | No | Heavy worker thinking setting. |
worker_backend | string | No | llm, acp, or null. |
worker_delegated_agent | string | null | No | Delegated agent for an acp worker. |
allowed_worker_backends | array | null | No | Backends a dispatch may name. |
worker_delegated_model | string | null | No | Claude model for an acp delegate. |
worker_delegated_effort | string | No | low, medium, high, xhigh, max, or null. |
worker_model | string | null | No | Model for an llm delegate when no routing tier applies. |
worker_thinking | string | No | off, on, low, medium, high, xhigh, max, or null. |
realtime_max_items | integer | No | Maximum Realtime items, from the larger of 1 and the current usage through 16777216. Default: 1048576. |
speech | object | No | Complete replacement speech configuration. It can be null. |
The fields id, uid, realm, created, created_at, and created_by are immutable. The routing and speech objects replace the existing configuration as a whole.
Request
Section titled “Request”curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&expect_revision=3&realm=global" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Answer with a short summary and a list of verification steps.", "model": "openai/gpt-5" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const bot = await client.agent.bots.update( 'chief', { instructions: 'Answer with a short summary and a list of verification steps.', model: 'openai/gpt-5' }, { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', expect_revision: 3, agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "address": "bot:global/chief", "allowed_agents": [], "allowed_computers": [], "allowed_worker_backends": [ "llm" ], "async": false, "autonomy": { "max": 10, "per_delegate_max": 3, "used": 0, "waiting_for_you": false }, "channels": [ { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "notes": [], "paired_count": 1, "requested_chats": 0, "state": "connecting" } ], "created": "2026-10-08T10:30:00Z", "created_by": { "kind": "system" }, "guardrail_check": "strict", "guardrails": "Never push to main.", "id": "chief", "instructions": "Answer with a short summary and a list of verification steps.", "mcp_hints": true, "model": "openai/gpt-5", "model_applies": "after_reset", "name": "Chief", "open_delegates": 1, "pending_gate": null, "queued": 0, "realm": "global", "realtime_items": { "max": 1048576, "used": 0 }, "revision": 4, "role": "Keeps the web app's releases moving.", "routing": null, "session_id": "5f0c2a91d3b44e7f", "session_model": "hoody-ai/hoody-free", "speech": null, "turn_running": false, "uid": "0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c", "wait_seconds": 15, "worker_backend": "llm", "worker_delegated_agent": "", "worker_delegated_effort": "", "worker_delegated_model": "", "worker_model": "", "worker_thinking": "", "yolo": false, "yolo_unapplied": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The body contained invalid values or exceeded a field limit. | Correct the request body. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
field_immutable | Field cannot be changed | The body named id, uid, realm, created, created_at, or created_by. | Remove the immutable field and create another Bot if its id or realm must change. |
upgrade_required | Renamed field | The request contains a field name that was renamed when Hoody computers replaced the old terminology. | Send the current field name from details.renamed. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "revision_mismatch", "message": "the Bot's settings changed since expect_revision; read the Bot again, then retry with its revision; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the change should apply to it. |
revision_mismatch | Revision mismatch | The Bot’s settings or guardrails changed after expect_revision was read. Nothing was changed. | Read the Bot again and retry with its current revision. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "model_unavailable", "message": "unknown model \"nope/not-a-model\": a model spec starts with a provider prefix (for example hoody-ai/); list the available models with GET /api/v1/agent/models", "details": { "reason": "unknown_model" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The model cannot start a Bot session. details.reason can be unknown_model, non_chat_provider, speech_model, not_tts, not_stt, provider_refused, or not_claude. | Choose an available chat or speech model, or send an empty model to use the bot agent’s own model. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
PUT /api/v1/agent/bots/{id}/guardrails
Section titled “PUT /api/v1/agent/bots/{id}/guardrails”Replaces the Bot’s guardrails. The Bot receives the new text before its next message. Delegates opened afterward receive it at the top of their first prompt. Open delegates keep the limits they were given.
An empty guardrails string removes every earlier guardrail.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents a change to a different Bot that now holds the same id. |
expect_revision | query | integer | No | The settings revision that was read. It prevents overwriting newer settings. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
guardrails | string | Yes | New limits. An empty string clears the existing guardrails. |
Request
Section titled “Request”curl -X PUT "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/guardrails?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&expect_revision=4&realm=global" \ -H "Content-Type: application/json" \ -d '{ "guardrails": "Never push to main. Never deploy without a successful test run." }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const bot = await client.agent.bots.setGuardrails( 'chief', { guardrails: 'Never push to main. Never deploy without a successful test run.' }, { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', expect_revision: 4, agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "address": "bot:global/chief", "allowed_agents": [], "allowed_computers": [], "allowed_worker_backends": [ "llm" ], "async": false, "autonomy": { "max": 10, "per_delegate_max": 3, "used": 0, "waiting_for_you": false }, "channels": [ { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "notes": [], "paired_count": 1, "requested_chats": 0, "state": "connecting" } ], "created": "2026-10-08T10:30:00Z", "created_by": { "kind": "system" }, "guardrail_check": "strict", "guardrails": "Never push to main. Never deploy without a successful test run.", "id": "chief", "instructions": "Answer with a short summary and a list of verification steps.", "mcp_hints": true, "model": "openai/gpt-5", "name": "Chief", "open_delegates": 1, "pending_gate": null, "queued": 0, "realm": "global", "realtime_items": { "max": 1048576, "used": 0 }, "revision": 5, "role": "Keeps the web app's releases moving.", "routing": null, "session_id": "5f0c2a91d3b44e7f", "session_model": "hoody-ai/hoody-free", "speech": null, "turn_running": false, "uid": "0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c", "wait_seconds": 15, "worker_backend": "llm", "worker_delegated_agent": "", "worker_delegated_effort": "", "worker_delegated_model": "", "worker_model": "", "worker_thinking": "", "yolo": false, "yolo_unapplied": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or the replacement would exceed the combined Bot settings limit. | Correct the request body or shorten the guardrails. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
upgrade_required | Renamed field | The request contains a field name that was renamed when Hoody computers replaced the old terminology. | Send the current field name from details.renamed. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "revision_mismatch", "message": "the Bot's settings changed since expect_revision; read the Bot again, then retry with its revision; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the change should apply to it. |
revision_mismatch | Revision mismatch | The Bot’s settings or guardrails changed after expect_revision was read. Nothing was changed. | Read the Bot again and retry with its current revision. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/{id}/reset
Section titled “POST /api/v1/agent/bots/{id}/reset”Moves the log to the archive and starts a new Bot session using the Bot’s current model. Delegates remain attached to the Bot. Messages not yet posted are sent to the new session.
A 503 response means the reset could not be confirmed. The log or session might already have changed, and retrying performs another reset.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents resetting a different Bot that now holds the same id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/reset?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.reset( 'chief', { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "archived": 30, "session_id": "c71d0e5a2b9f4a08"}| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The Bot’s new session id. |
archived | integer | Yes | Number of log rows moved to the archive. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "bot_changed", "message": "this id now names another Bot than expect_uid: the Bot you read was deleted; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the reset should apply to it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request exceeds the configured limit, which defaults to 8 MiB. | Reduce the request size. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The reset could not be confirmed. The log or session might already have changed. | Read the Bot before retrying because another reset performs another reset. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
DELETE /api/v1/agent/bots/{id}
Section titled “DELETE /api/v1/agent/bots/{id}”Deletes the Bot, its log, and its archive. Before deletion, the agent makes a best-effort attempt to stop working or waiting delegates. The Bot’s session and delegates remain listed as sessions and end like idle sessions.
Deleting chief removes it. Its next use creates a new default Bot.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents deleting a different Bot that now holds the same id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.bots.delete( 'chief', { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', agentRealm: 'global' });Response
Section titled “Response”Media type: none
The response has no body.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "bot_changed", "message": "this id now names another Bot than expect_uid: the Bot you read was deleted; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the deletion should apply to it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
store_failed | Agent store failed | An agent store could not be read, parsed, locked, or written, so deletion did not complete. | Retry once, then repair the named store inside the computer if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The Bot is being stopped or the agent cannot service the request. The response includes Retry-After when the Bot is being stopped. | Honor Retry-After and send the delete again. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/resume
Section titled “POST /api/v1/agent/bots/resume”Resumes suspended Bots in the selected realm. With ?realm=all, it resumes suspended Bots in every realm served by the login, global included. Calling it again returns an empty list.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | query | string | No | Realm whose Bots to resume: global, a 24-hex realm id, or all. |
X-Hoody-Realm | header | string | No | Realm whose Bots to resume: global or a 24-hex realm id. The header does not accept all. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/resume?realm=all"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.resumeAll({ agentRealm: 'all' });Response
Section titled “Response”Media type: application/json
{ "resumed": [ { "id": "chief", "realm": "global" } ]}| Name | Type | Required | Description |
|---|---|---|---|
resumed | array | Yes | Bots resumed by this call, in realm and id order. |
resumed[].id | string | Yes | The Bot id. |
resumed[].realm | string | Yes | The Bot’s realm. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global, a 24-hex realm id, or all. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The selected realm is not served by this login. | Select a realm served by the login. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves a Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request exceeds the configured limit, which defaults to 8 MiB. | Reduce the request size. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | A Bot could not be resumed yet and remains suspended. | Retry in a moment. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
Send messages and follow logs
Section titled “Send messages and follow logs”POST /api/v1/agent/bots/{id}/messages
Section titled “POST /api/v1/agent/bots/{id}/messages”Queues a message for the Bot and returns 202. If the Bot is free, the message is posted within a few seconds. If the Bot is busy, the response has state: "queued" and the message is posted when the current turn ends.
Messages accepted before the Bot’s next post are delivered together and in order. The reply appears on GET /api/v1/agent/bots/{id}/stream and in GET /api/v1/agent/bots/{id}/log.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
Idempotency-Key | header | string | No | Retry key from 1 to 255 printable ASCII characters with no whitespace. It must not begin with compat: or chan:. The same key and text return the same message without queueing it again. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Message text, at most 64 KiB. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/messages?realm=global" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: release-notes-2026-10-08" \ -d '{ "text": "Ship the release notes." }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.bots.messages.send( 'chief', { text: 'Ship the release notes.' }, { idempotencyKey: 'release-notes-2026-10-08', agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "message_id": "msg-6f1c0e2a-3b9d-4c51-9a7e-2d4b8c1f0a63", "state": "posted", "turn_id": "turn-k3x9-4"}| Name | Type | Required | Description |
|---|---|---|---|
message_id | string | Yes | The accepted message id. Its log row carries this value. |
state | string | Yes | posted: the Bot turn started (turn_id). queued: the message waits for the Bot’s current turn to end. dropped: the Bot dropped the message before posting it and never will; reason says why, its key keeps answering dropped, so send it again under a new key. |
turn_id | string | No | Bot turn that posted the message. Present when state is posted. |
reason | string | No | When state is dropped: access_revoked (the chat-app sender is no longer allowed to send it) or key_conflict (the Bot could not deliver it). |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The message body or idempotency key was invalid. | Send a valid text value and a valid idempotency key. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the request body below the configured limit; split a large payload into smaller requests. |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this Idempotency-Key was used for a different message", "details": { "message_id": "msg-6f1c0e2a-3b9d-4c51-9a7e-2d4b8c1f0a63" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The key already accepted a different message for this Bot. | Use a fresh key for a different message or resend the identical message to get its receipt. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
idempotency_keys_exhausted | Too many remembered keys | The Bot already remembers 4096 idempotency keys. The message was not queued. | Send the message later or omit the idempotency key. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The message was not queued. | Send the message again. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots/{id}/messages/by-key/{key}
Section titled “GET /api/v1/agent/bots/{id}/messages/by-key/{key}”Reads what became of a message accepted under an idempotency key. It returns the message id and whether the message is queued, posted, or dropped. Reading it queues and posts nothing.
A 404 message_not_found response does not prove that the message was never accepted. The key can expire after 24 hours, or the message can still be on its way. Read the Bot log before sending the message again.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
key | path | string | Yes | Idempotency key, from 1 to 255 printable ASCII characters with no whitespace. URL-encode it. It must not begin with compat: or chan:. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/messages/by-key/release-notes-2026-10-08?realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const message = await client.agent.bots.messages.getByKey( 'chief', 'release-notes-2026-10-08', { agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "message_id": "msg-6f1c0e2a-3b9d-4c51-9a7e-2d4b8c1f0a63", "state": "posted", "turn_id": "turn-k3x9-4"}| Name | Type | Required | Description |
|---|---|---|---|
message_id | string | Yes | The message id. |
state | string | Yes | posted: the Bot turn started (turn_id). queued: the message waits for the Bot’s current turn to end. dropped: the Bot dropped the message before posting it and never will; reason says why, its key keeps answering dropped, so send it again under a new key. |
turn_id | string | No | Bot turn that posted the message. Present when state is posted. |
reason | string | No | When state is dropped: access_revoked (the chat-app sender is no longer allowed to send it) or key_conflict (the Bot could not deliver it). |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The key or another request parameter was invalid. | Use a key from 1 to 255 printable ASCII characters with no whitespace that does not begin with compat: or chan:. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
message_not_found | No message with this key | The Bot does not remember a message under this key. This can mean the key expired or the message is still in transit. A dropped message is remembered under its key and answers 200 with state dropped. | Read the Bot log before sending the message again. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots/{id}/log
Section titled “GET /api/v1/agent/bots/{id}/log”Returns the Bot’s log in order: posted messages, Bot replies, and delegate events. Pages by seq. Pass next_since back as since while has_more is true.
Use tail=true to open at the newest rows, then use before to read older pages. POST /api/v1/agent/bots/{id}/forget moves the rows to the archive.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
since | query | integer | No | Return rows whose seq is greater than this value. Default: 0. |
limit | query | integer | No | Maximum rows to return. Uses 100 when omitted or 0, and at most 500. Values above 500 are accepted and read at most 500 rows. Negative or non-integer values return 400. A page query returns 400. |
before | query | integer | No | Read backward from this sequence. It cannot be combined with since or tail. |
tail | query | boolean | No | Return the newest rows, oldest first. It cannot be combined with since or before. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/log?since=0&limit=100&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
for await (const row of client.agent.bots.getLogsIterator('chief', { since: 0, limit: 100, agentRealm: 'global' })) { console.log(row);}Response
Section titled “Response”Media type: application/json
{ "has_more": false, "items": [ { "at": "2026-10-08T10:31:07Z", "delegate_title": "Run the tests", "kind": "report", "role": "event", "seq": 12, "session_id": "9a1be4c07d2f4c11", "text": "[report] 9a1be4c07d2f4c11 \"Run the tests\" (self, default) completed: The tests pass." } ], "next_since": 12}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The pagination parameters were invalid or conflicting. | Use one of since, before, or tail. limit uses 100 when omitted or 0; values above 500 are accepted and capped at 500. Negative or non-integer values, and page, return 400. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots/{id}/archive
Section titled “GET /api/v1/agent/bots/{id}/archive”Returns log rows moved out of the active log by forget or reset, oldest first. Pages by seq. Pass next_since as since while has_more is true.
The archive route refuses tail with 400 bad_request. Use before to read backward from the end.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
since | query | integer | No | Return rows whose seq is greater than this value. Default: 0. |
limit | query | integer | No | Maximum rows to return. Uses 100 when omitted or 0, and at most 500. Values above 500 are accepted and read at most 500 rows. Negative or non-integer values return 400. A page query returns 400. |
before | query | integer | No | Read backward from this sequence. It cannot be combined with since or tail. |
tail | query | boolean | No | Not accepted by the archive route. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/archive?since=0&limit=100&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
for await (const row of client.agent.bots.getArchiveIterator('chief', { since: 0, limit: 100 })) { console.log(row);}Response
Section titled “Response”Media type: application/json
{ "has_more": false, "items": [ { "at": "2026-10-08T10:31:07Z", "delegate_title": "Run the tests", "kind": "report", "role": "event", "seq": 12, "session_id": "9a1be4c07d2f4c11", "text": "[report] 9a1be4c07d2f4c11 \"Run the tests\" (self, default) completed: The tests pass." } ], "next_since": 12}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The pagination parameters were invalid or conflicting. The archive does not accept tail. | Use since or before. limit uses 100 when omitted or 0; values above 500 are accepted and capped at 500. Negative or non-integer values, and page, return 400. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
GET /api/v1/agent/bots/{id}/stream
Section titled “GET /api/v1/agent/bots/{id}/stream”Follows the Bot’s finished log rows as Server-Sent Events.
The stream first sends a state frame containing the Bot, then sends rows after since, then sends each new row as it is written. A new state frame is sent whenever the Bot changes. Row frame ids are their seq values.
Reconnect with Last-Event-ID or ?since=<last id>. A cursor whose rows were archived, or one ahead of the log, receives a lagged frame with code replay_gap. A forget or reset while the stream is open sends an archived frame. An end frame is sent when the Bot is deleted or the server ends the stream. Heartbeat comments are sent every 15 seconds.
This stream contains finished rows only. To follow reply text as it is generated, follow the Bot’s own session stream.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
since | query | integer | No | Return rows whose seq is greater than this value. Default: 0. |
Last-Event-ID | header | string | No | Resume cursor containing the last received event id. It overrides since. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl -N "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/stream?since=0&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const stream = await client.agent.bots.streamLogs('chief', { since: 0, agentRealm: 'global' });
for await (const event of stream) { console.log(event);}Response
Section titled “Response”Media type: text/event-stream
The body is an SSE byte stream. Each frame uses event: and data: lines, and row frames also carry the row sequence as the SSE event id. Frames are separated by a blank line, and heartbeat frames are SSE comments.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The cursor or another request parameter was invalid. | Use a non-negative integer since or a valid Last-Event-ID. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
Archive a conversation
Section titled “Archive a conversation”POST /api/v1/agent/bots/{id}/forget
Section titled “POST /api/v1/agent/bots/{id}/forget”Moves the log to the archive and clears the Bot session’s conversation. The Bot keeps its settings and delegates, and receives its guardrails again before its next message.
A reply the Bot was writing when you forget is still written to the new log when its turn ends.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents changing a different Bot that now holds the same id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/forget?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.clearConversation( 'chief', { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "archived": 12}| Name | Type | Required | Description |
|---|---|---|---|
archived | integer | Yes | Number of rows moved to the archive. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "bot_changed", "message": "this id now names another Bot than expect_uid: the Bot you read was deleted; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the operation should apply to it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request exceeds the configured limit, which defaults to 8 MiB. | Reduce the request size. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/{id}/purge
Section titled “POST /api/v1/agent/bots/{id}/purge”Deletes the rows that forget and reset moved to the archive. The active log is not changed.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
expect_uid | query | string | No | The Bot uid that was read. It prevents changing a different Bot that now holds the same id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/purge?expect_uid=0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.clearArchive( 'chief', { expect_uid: '0199c3a2-6f10-7c4e-9b2a-3d5e8f1a2b4c', agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "purged": true}| Name | Type | Required | Description |
|---|---|---|---|
purged | boolean | Yes | Always true. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or contained invalid parameters. | Correct the request parameters. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "bot_changed", "message": "this id now names another Bot than expect_uid: the Bot you read was deleted; nothing was changed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bot_changed | Bot changed | expect_uid does not name the Bot that currently holds the id. Nothing was changed. | Read the Bot again and decide whether the operation should apply to it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request exceeds the configured limit, which defaults to 8 MiB. | Reduce the request size. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
Manage delegates and gates
Section titled “Manage delegates and gates”GET /api/v1/agent/bots/{id}/delegates
Section titled “GET /api/v1/agent/bots/{id}/delegates”Lists the sessions the Bot opened, both open and closed, ordered by opening time. Use state=open or state=closed to filter.
Each delegate is an ordinary agent session. Open delegates also report how soon they read messages and their current activity. The response includes messages the delegate has not read and its last command.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
state | query | string | No | open or closed. If omitted, both states are included. |
page | query | integer | No | One-based page number. |
limit | query | integer | No | Maximum items per page. 0 disables pagination. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request
Section titled “Request”curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/delegates?state=open&page=1&limit=20&realm=global"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
for await (const delegate of client.agent.bots.listDelegatesIterator('chief', { state: 'open' })) { console.log(delegate.session_id);}Response
Section titled “Response”Media type: application/json
{ "items": [ { "agent": "", "capability": "next_step", "computer": "", "current_step": { "kind": "gate", "since": "2026-10-08T10:31:02Z" }, "last_turn_id": "turn-p2m7-1", "model": "hoody-ai/hoody-free", "open_gates": [ { "gate_id": "gate-k3x9-2", "generation": 2, "summary": "bash: go test ./...", "type": "confirm" } ], "opened_at": "2026-10-08T10:30:40Z", "route": { "applied": true, "judge": "openrouter/typesafe/jev-1.14", "mode": "auto", "model": "hoody-ai/hoody-free", "policy": "traits-v1", "reason": "no heavy trait", "routed_by": "jev", "thinking": "off", "traits": { "bug_review": 0.02, "concurrency": 0.02, "distributed": 0.01, "hard_math": 0.01, "large_change": 0.03, "migration": 0.01, "new_design": 0.05, "security": 0.01, "unknown_cause": 0.04 }, "worker": "light" }, "session_id": "9a1be4c07d2f4c11", "state": "open", "title": "fix the flaky test" } ], "meta": { "total": 1 }}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The state or pagination parameters were invalid. | Use open or closed for state, and valid pagination values. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/{id}/delegates/{sid}/stop
Section titled “POST /api/v1/agent/bots/{id}/delegates/{sid}/stop”Stops one delegate’s work at once. Its running turn, background tasks, workflow runs, and shells end, while its loops pause. Messages from the Bot that the delegate has not read are dropped. With close: true, the delegate session is also closed.
The Bot is not stopped. Use the Bot cancellation route to stop the Bot’s own running turn.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
sid | path | string | Yes | The delegate session id. |
Idempotency-Key | header | string | No | Opaque retry key from 1 to 255 printable ASCII characters with no whitespace. It must not begin with chan:. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
close | boolean | No | Also close the delegate session permanently. Default: false. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/delegates/9a1be4c07d2f4c11/stop?realm=global" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: stop-flaky-test-2026-10-08" \ -d '{ "close": true }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.stopDelegate( 'chief', '9a1be4c07d2f4c11', { close: true }, { idempotencyKey: 'stop-flaky-test-2026-10-08', agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "closed": true, "command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9", "session_id": "9a1be4c07d2f4c11", "state": "committed", "stopped": [ { "id": "9a1be4c07d2f4c11", "kind": "session", "outcome": "stopped" } ], "title": "fix the flaky test"}| Name | Type | Required | Description |
|---|---|---|---|
command_id | string | Yes | Stop command id. |
session_id | string | Yes | Delegate session id. |
title | string | Yes | Title given by the Bot. |
state | string | Yes | committed or queued. |
stopped | array | Yes | Work on which the stop acted. |
stopped[].kind | string | Yes | session, task, workflow_run, bash_job, or loop. |
stopped[].id | string | Yes | Id of the stopped work. |
stopped[].outcome | string | Yes | stopped, already_done, or failed. |
stopped[].detail | string | No | Why a stop failed. |
stopped[].cleanup | string | No | detached_may_survive when a detached process might still run. |
cleanup | string | No | detached_may_survive when a detached process might still run. |
closed | boolean | Yes | Whether the delegate session was closed. |
dropped_messages | integer | No | Bot messages dropped because they had not been read. |
Media type: application/json
{ "closed": false, "command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9", "session_id": "9a1be4c07d2f4c11", "state": "queued", "stopped": [], "title": "fix the flaky test"}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The body or idempotency key was invalid. | Send a valid close value and a valid idempotency key that does not begin with chan:. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm, Bot, or delegate does not exist in the selected realm. | Verify the realm, Bot id, and delegate session id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
session_closed | Session closed | The delegate session is closed or a closing stop is already in progress. | Attach the session again or start another session. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this Idempotency-Key was used for a different stop"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The key was already used for a different delegate or a different close value. Nothing was sent. | Use a fresh key for a different stop or resend the identical stop. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The stop outcome is not confirmed. The stop might be recorded, in flight, or already reached the delegate. | Retry with the same idempotency key and check the delegate’s last_command. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/{id}/cancel
Section titled “POST /api/v1/agent/bots/{id}/cancel”Stops the Bot’s running turn named by turn_id. The Bot’s turn_id is present while turn_running is true.
A turn that has already ended is not touched, and later turns are not affected. The Bot’s delegates keep running.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
turn_id | string | Yes | The running Bot turn to stop. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/cancel?realm=global" \ -H "Content-Type: application/json" \ -d '{ "turn_id": "turn-k3x9-4" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.cancelTurn( 'chief', { turn_id: 'turn-k3x9-4' }, { agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "status": "ok", "turn_id": "turn-k3x9-4", "matched": true}| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | ok when the stop was sent. |
turn_id | string | No | Turn named by the request. |
matched | boolean | No | true when it was the Bot’s running turn, false when nothing was stopped. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request body or another parameter was invalid. | Send the running Bot turn_id. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not "", global, or a 24-hex realm id. | Send a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | It is not known whether the stop reached the Bot’s session. | Send the same stop again. It cannot stop a later turn. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
POST /api/v1/agent/bots/{id}/gate
Section titled “POST /api/v1/agent/bots/{id}/gate”Answers the approval or question parked on the Bot’s own session. Use the gate_id, generation, and type from pending_gate in GET /api/v1/agent/bots/{id}.
An approval uses confirm, and a question uses answer. Send exactly one of them.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The Bot id. |
X-Hoody-Realm | header | string | No | Realm in which to look up the Bot: global or a 24-hex realm id. |
realm | query | string | No | Query alias for X-Hoody-Realm. It is read when the header is absent. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
gate_id | string | Yes | pending_gate.gate_id from the Bot resource. |
generation | integer | Yes | pending_gate.generation from the Bot resource. |
request_id | string | No | Your id for an approval decision, up to 64 characters from A-Z, a-z, 0-9, ., _, and -. |
confirm | object | No | Decision for an approval. Exactly one of confirm or answer is required. |
confirm.approved | boolean | No | true approves this call, false refuses it. It is required within confirm. |
confirm.reason | string | No | Reason for refusing the call. Maximum length: 500. |
answer | object | No | Answer to a question. Exactly one of confirm or answer is required. |
answer.answer | string | No | Non-blank answer text. It is required within answer. |
Request
Section titled “Request”curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/gate?realm=global" \ -H "Content-Type: application/json" \ -d '{ "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3, "request_id": "release-approval-2026-10-08", "confirm": { "approved": true } }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.bots.answerGate( 'chief', { gate_id: 'gate-9f2c4e1ab07d3355-3', generation: 3, request_id: 'release-approval-2026-10-08', confirm: { approved: true } }, { agentRealm: 'global' });Response
Section titled “Response”Media type: application/json
{ "status": "ok", "resolved": {}, "replayed": false}| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | ok when the Bot session consumed the decision. |
resolved | object | No | The session’s resolution of the gate. |
replayed | boolean | No | true when the same answer was sent again after the question accepted it. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The gate decision body was malformed or invalid. | Send gate_id, generation, and exactly one valid confirm or answer object. |
realm_scope_unsupported | Realm scope unsupported | A realm selector conflicted with the agent’s realm scope. | Omit the selector or name the agent’s current realm. |
invalid_realm | Invalid realm selector | The realm selector was not global or a 24-hex realm id. | Send a valid realm selector. |
approved_required | Decision missing | confirm.approved was omitted or was not a boolean. | Send approved: true to approve or approved: false to deny. |
upgrade_required | Renamed field | The request contains a field name that was renamed when Hoody computers replaced the old terminology. | Send the current field name from details.renamed. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The realm or Bot does not exist in the selected realm. | Verify the realm and Bot id. |
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt, so the request fails closed. | Select a valid, reachable realm. |
gate_already_resolved | Gate already resolved | The gate already ended, so this decision was not applied. | Do not resend the decision. Read the current session state and answer any new gate. |
gate_decision_pending | Gate decision pending | A decision for this gate is in flight and its outcome is not known. | Retry the same decision to learn its outcome. |
gate_already_answered | Gate already answered | The question was already answered, possibly with a different answer. | Retry with the same answer only if you need the original acknowledgement. |
gate_cancelled | Gate cancelled | The gate ended without consuming the decision. | Do not retry this decision. Read the current session state. |
stale_gate | Stale gate | The supplied gate id or generation does not match the currently parked gate. | Answer the gate named in details, or read pending_gate again. |
no_pending_gate | No pending gate | No approval or question is parked on the Bot’s own session. | Dispatch a turn and answer the gate it parks. |
bot_owned_elsewhere | Bot served by another agent | Another agent process on this computer serves the Bot, or its lock cannot be taken. The response includes Retry-After: 5. | Retry after the indicated delay or reach the Bot through the agent that serves it. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured limit, which defaults to 8 MiB. | Reduce the body below the configured limit. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. | Honor Retry-After and retry at a lower rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry, then inspect the agent logs if the failure persists. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The agent could not service the request because it was busy or a stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |
decision_unconfirmed | Decision unconfirmed | The decision was forwarded, but the daemon did not confirm whether it was consumed. It may still apply. | Retry the identical decision with the original gate_id and generation. |