Skip to content

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

Hoody.com

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.

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.

NameTypeRequiredDescription
idstringYesThe Bot id, unique within its realm and fixed at creation.
uidstringYesThe globally unique Bot id, fixed at creation.
realmstringYesThe Bot’s realm, either global or a realm id.
addressstringYesThe Bot’s address in messages and logs, in the form bot:<realm>/<id>.
namestringYesDisplay name.
rolestringYesWhat the Bot is for. Empty when unset.
instructionsstringYesInstructions about tone or format. They do not override rules or guardrails and are not passed to delegates.
session_idstringYesThe Bot’s own session. Empty until its first message is posted.
modelstringYesModel selected for the Bot’s session. Empty means the bot agent’s own model.
session_modelstringNoModel reported by the current session. It can differ from model until the Bot is reset.
guardrailsstringYesLimits that apply to the Bot and every delegate it opens.
allowed_computersarrayYesComputers on which the Bot may open delegates. Empty means any.
allowed_agentsarrayYesAgents with which the Bot may open delegates. Empty means any.
yolobooleanYesWhether every delegate runs with tool approvals granted automatically.
guardrail_checkstringYesGuardrail check mode: strict, lenient, or off.
asyncbooleanYesWhether compatible API answers return before delegates show their first step. Default: false.
wait_secondsintegerYesCompatible API wait time for delegates, from 1 to 60. Default: 15.
mcp_hintsbooleanYesWhether MCP results end with counts of new messages and approvals. Default: true.
routingobjectYesRouting configuration. It can be null.
routing.modestringYesRouting mode: off, suggest, or auto.
routing.lightobjectNoWorker for tasks without a heavy trait. Required unless routing is off.
routing.light.modelstringYesModel for the light worker.
routing.light.thinkingstringNoThinking setting: empty, off, on, low, medium, high, xhigh, or max.
routing.heavyobjectNoWorker for tasks with a heavy trait. Required unless routing is off.
routing.heavy.modelstringYesModel for the heavy worker.
routing.heavy.thinkingstringNoThinking setting: empty, off, on, low, medium, high, xhigh, or max.
worker_backendstringYesDefault delegate backend: llm or acp.
worker_delegated_agentstringYesDelegated agent for an acp worker, such as claude. Empty when unset.
allowed_worker_backendsarrayYesBackends a dispatch may name.
worker_delegated_modelstringYesClaude model for an acp delegate. Empty means the configured or default model.
worker_delegated_effortstringYesEffort for an acp delegate: low, medium, high, xhigh, or max. Empty means its own default.
worker_modelstringYesModel for an llm delegate when no routing tier applies. Empty means the agent’s model.
worker_thinkingstringYesThinking setting for worker_model. Empty means the model’s default.
speechobjectYesSpeech settings. It can be null.
speech.tts_modelstringNoText-to-speech model.
speech.stt_modelstringNoSpeech-to-text model. Empty means the agent’s default.
speech.voicestringNoVoice for tts_model.
speech.languagestringNoSpeech language, such as en or auto.
speech.speednumberNoSpeaking speed for tts_model.
speech.stt_promptstringNoWords expected by the speech-to-text model. Maximum length: 500.
speech.speak_wakesbooleanNoWhether delegate reports are spoken. Default: false.
speech.speak_gatesbooleanNoWhether waiting approvals and questions are announced. Default: true.
speech.limitsobjectNoThe Bot’s daily speech limits.
speech.limits.tts_charsintegerNoCharacters read aloud per UTC day. 0 disables speech output.
speech.limits.stt_secondsintegerNoSeconds transcribed per UTC day. 0 disables spoken messages.
yolo_unappliedarrayYesOpen delegates whose approval mode does not yet match yolo.
yolo_unapplied[].session_idstringYesDelegate session id.
yolo_unapplied[].statestringYespending or refused.
yolo_unapplied[].reasonstringNoWhy the last attempt did not apply.
createdstringYesCreation time in RFC 3339 format.
created_byobjectYesCreator record. It grants no access.
created_by.kindstringYesuser, api, or system.
created_by.idstringNoCreator id, when known.
revisionintegerYesSettings revision. It increases after settings or guardrails are written.
autonomyobjectYesLimits and usage for work the Bot starts without a new user message.
autonomy.usedintegerYesAutonomous actions used since your last message.
autonomy.maxintegerYesMaximum autonomous actions between user messages.
autonomy.per_delegate_maxintegerYesMaximum autonomous actions sent to one delegate.
autonomy.waiting_for_youbooleanYesWhether the Bot has reached an autonomy limit.
realtime_itemsobjectYesRealtime item usage and limit.
realtime_items.usedintegerYesRealtime items seen. It can be null when they cannot be read.
realtime_items.maxintegerYesMaximum Realtime items the Bot can record.
open_delegatesintegerYesNumber of open delegate sessions.
queuedintegerYesMessages and delegate events waiting to be posted.
turn_runningbooleanYesWhether the Bot is working on a turn.
turn_idstringNoRunning turn id, present while turn_running is true.
pending_gateobjectYesApproval or question parked on the Bot’s own session. It can be null.
pending_gate.session_idstringYesBot session holding the gate.
pending_gate.gate_idstringYesAnswerable gate id.
pending_gate.typestringYesconfirm or question.
pending_gate.summarystringYesOne-line summary of what the gate asks.
pending_gate.generationintegerYesGate generation to echo when answering.
channelsarrayYesSummary of the Bot’s chat channels.
channels[].idstringYesChannel id.
channels[].kindstringYesdiscord, slack, or telegram.
channels[].labelstringYesYour label for the channel.
channels[].statestringYesChannel connection state: connecting, connected, awaiting_owner, degraded, standby, conflict, auth_failed, paused, realm_unserved, stopping, or stopped.
channels[].state_reasonstringNoReason for the current channel state.
channels[].paired_countintegerYesNumber of paired people.
channels[].requested_chatsintegerYesChats waiting for approval.
channels[].notesarrayYesNotes from the last credential check.
channels[].notes[].codestringYesNote code.
channels[].notes[].fieldstringYesSetting the note concerns.
channels[].notes[].reasonstringNoReason for the note.
speech_usageobjectNoCurrent speech usage and limits. Absent when usage cannot be read.
speech_usage.daystringYesUTC usage date in YYYY-MM-DD format.
speech_usage.resets_atstringYesNext UTC reset time in RFC 3339 format.
speech_usage.tts_charsnumberYesCharacters read aloud today.
speech_usage.stt_secondsnumberYesSeconds transcribed today.
speech_usage.limitsobjectYesThe Bot’s effective daily limits.
speech_usage.limits.tts_charsintegerNoDaily character limit.
speech_usage.limits.stt_secondsintegerNoDaily transcription limit.
speech_usage.limits.sourceobjectNoSource of each limit, bot or default.
speech_usage.limits.source.tts_charsstringNoCharacter limit source.
speech_usage.limits.source.stt_secondsstringNoTranscription limit source.
speech_usage.realm_usedobjectYesRealm-wide speech usage today.
speech_usage.realm_used.tts_charsnumberNoRealm characters read aloud today.
speech_usage.realm_used.stt_secondsnumberNoRealm seconds transcribed today.
speech_usage.realm_limitsobjectYesRealm-wide daily limits.
speech_usage.realm_limits.tts_charsintegerNoRealm daily character limit.
speech_usage.realm_limits.stt_secondsintegerNoRealm daily transcription limit.
urlsobjectYesCompatible client URLs for the Bot.
urls.openaistringYesOpenAI-compatible base URL.
urls.anthropicstringYesAnthropic-compatible base URL.
urls.mcpstringYesMCP Streamable HTTP URL.
model_appliesstringYesWhen model takes effect: after_reset or next_session.
NameTypeRequiredDescription
itemsarrayYesThe Bots in the selected realm. A Bot served by another agent process appears as a locked row.
metaobjectYesPagination metadata.
meta.totalintegerNoTotal number of Bots across all pages.
meta.pageintegerNoOne-based page number, present when limit is greater than 0.
meta.limitintegerNoItems per page, present when limit is greater than 0.
suspended_countintegerYesNumber 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.

Both log and archive endpoints return the same page structure. Archive rows are rows previously moved out of the active log.

NameTypeRequiredDescription
itemsarrayYesRows in sequence order.
items[].seqintegerYesRow position. It increases by one per row and survives forget.
items[].atstringYesTime the row was written in RFC 3339 format.
items[].rolestringYesuser, bot, event, or system.
items[].textstringYesRow text.
items[].session_idstringNoBot or delegate session the row concerns.
items[].turn_idstringNoBot turn ended by a reply row.
items[].message_idstringNoAccepted message id on a user row.
items[].message_idsarrayNoMessage ids answered by a reply or turn-result row.
items[].fromobjectNoWho wrote the row.
items[].from.kindstringYesuser, bot, delegate, or system.
items[].from.idstringNoSender id within the kind.
items[].triggerstringNohuman, wake, or clear.
items[].senderobjectNoDoor through which a user message arrived.
items[].sender.viastringNoDoor name.
items[].schema_versionintegerNoRow format version.
items[].kindstringNoRuntime row kind: budget, channel, error, gate, gone, limit, not_sent, note, provider, realtime, report, reset, route, stop, or waiter.
items[].fail_kindstringNoCause 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_titlestringNoDelegate title when the row was written.
items[].voiceobjectNoVoice-message metadata.
items[].voice.originstringYesrest, mcp, ws, realtime, or twilio.
items[].voice.duration_msintegerYesAudio duration in milliseconds.
items[].voice.langstringNoTranscribed language.
items[].voice.connstringNoVoice connection id.
items[].voice.uttintegerNoVoice connection utterance number.
next_sinceintegerYesSequence to pass as since to read the next page.
has_morebooleanYesWhether another page is available.
beforeintegerNoSequence to pass as before when reading backward.
NameTypeRequiredDescription
itemsarrayYesDelegate sessions opened by the Bot.
items[].session_idstringYesDelegate session id.
items[].computerstringYesComputer on which the delegate runs. Empty for the agent’s own computer.
items[].agentstringYesAgent on which the delegate runs. Empty for the default agent.
items[].titlestringYesTitle given by the Bot.
items[].modelstringYesModel reported by the delegate session.
items[].backendstringYesllm or acp.
items[].delegated_agentstringYesDelegated agent for an acp delegate. Empty otherwise.
items[].statestringYesopen or closed.
items[].opened_atstringYesOpening time in RFC 3339 format.
items[].close_reasonstringNoWhy a closed delegate ended.
items[].last_turn_idstringYesLast delegate turn known to the Bot.
items[].routeobjectYesRouting decision for the dispatch. It can be null.
items[].route.modestringYessuggest or auto.
items[].route.appliedbooleanYesWhether the selected worker was applied.
items[].route.workerstringNolight or heavy.
items[].route.modelstringNoSelected worker model.
items[].route.thinkingstringNoSelected worker thinking setting.
items[].route.routed_bystringYesjev, explicit, length, or fallback.
items[].route.reasonstringYesWhy the route was selected.
items[].route.traitsobjectNoTrait probabilities returned by the routing checker.
items[].route.judgestringNoRouting checker model.
items[].route.policystringYesRouting policy version.
items[].capabilitystringNonext_step, turn_end, or unsupported.
items[].current_stepobjectNoCurrent coarse activity of an open delegate.
items[].current_step.kindstringYesmodel, tool, gate, or idle.
items[].current_step.toolstringNoTool currently running.
items[].current_step.sincestringYesTime the current step began.
items[].open_gatesarrayYesApprovals and questions the delegate is waiting on.
items[].open_gates[].gate_idstringYesAnswerable gate id.
items[].open_gates[].typestringYesconfirm or question.
items[].open_gates[].summarystringYesOne-line summary.
items[].open_gates[].generationintegerYesGate generation.
items[].queued_commandsintegerNoBot messages the delegate has not read.
items[].last_commandobjectNoLast message or stop sent to the delegate.
items[].last_command.command_idstringNoDelegate session command id.
items[].last_command.kindstringYesmessage, interrupt, or stop.
items[].last_command.statestringYessending, queued, committed, superseded, refused, or failed.
items[].last_command.howstringNonext_step, new_turn, or stop.
items[].last_command.fromstringYesbot or user.
items[].last_command.atstringYesTime the command was sent.
items[].last_command.reasonstringNoWhy a command was superseded, refused, or failed.
metaobjectYesPagination metadata.
meta.totalintegerNoTotal delegates across all pages.
meta.pageintegerNoOne-based page number.
meta.limitintegerNoItems per page.

JSON error responses use these fields:

NameTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoStructured error details when available.

Creates a Bot. The Bot’s own session opens when its first message is posted.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoRealm in which to create the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.

All body fields are optional.

NameTypeRequiredDescription
idstringNoBot id matching ^[a-z0-9][a-z0-9_-]{0,63}$. If omitted, one is generated.
namestringNoDisplay name. If omitted, it defaults to id.
rolestringNoWhat the Bot is for. Maximum length: 1000.
instructionsstringNoInstructions about tone or format. Maximum length: 4000.
modelstringNoModel for the Bot’s session. Empty means the bot agent’s own model.
guardrailsstringNoLimits applied to the Bot and every delegate it opens.
allowed_computersarrayNoComputers on which delegates may run. Empty or omitted means any.
allowed_agentsarrayNoAgents with which delegates may run. Empty or omitted means any.
yolobooleanNoWhether every delegate receives automatic tool approvals. Default: false.
guardrail_checkstringNostrict, lenient, or off.
asyncbooleanNoWhether compatible API answers return immediately. Default: false.
wait_secondsintegerNoFrom 1 to 60. Default: 15.
mcp_hintsbooleanNoWhether MCP results include pending-message and approval counts. Default: true.
routingobjectNoRouting configuration. It can be null. Default: off.
routing.modestringNooff, suggest, or auto. Required within a routing object.
routing.lightobjectNoLight worker. Required unless routing is off.
routing.light.modelstringNoLight worker model. Required within routing.light.
routing.light.thinkingstringNoLight worker thinking setting.
routing.heavyobjectNoHeavy worker. Required unless routing is off.
routing.heavy.modelstringNoHeavy worker model. Required within routing.heavy.
routing.heavy.thinkingstringNoHeavy worker thinking setting.
worker_backendstringNollm, acp, or null. Default: llm.
worker_delegated_agentstring | nullNoDelegated agent for an acp worker. It is required while acp is allowed.
allowed_worker_backendsarray | nullNoBackends a dispatch may name. If omitted, worker_backend alone applies.
worker_delegated_modelstring | nullNoClaude model for an acp delegate.
worker_delegated_effortstringNolow, medium, high, xhigh, max, or null. Empty uses Claude Code’s default.
worker_modelstring | nullNoModel for an llm delegate when no routing tier applies.
worker_thinkingstringNooff, on, low, medium, high, xhigh, max, or null.
speechobjectNoSpeech 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.

Terminal window
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."
}'

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

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.

NameInTypeRequiredDescription
realmquerystringNoRealm to list: global, a 24-hex realm id, or all. all is accepted only here.
pagequeryintegerNoOne-based page number.
limitqueryintegerNoMaximum items per page. 0 disables pagination.
X-Hoody-RealmheaderstringNoRealm to list: global or a 24-hex realm id. The header does not accept all.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots?realm=global&page=1&limit=20"

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
}

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief?realm=global"

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

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents a change to a different Bot that now holds the same id.
expect_revisionqueryintegerNoThe settings revision that was read. It prevents overwriting newer settings.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
namestringNoDisplay name.
rolestringNoWhat the Bot is for. Empty clears it. Maximum length: 1000.
instructionsstringNoInstructions about tone or format. Empty clears them. Maximum length: 4000.
modelstringNoModel for the Bot’s next session. Empty uses the bot agent’s own model.
allowed_computersarrayNoComputers on which delegates may run. Empty means any.
allowed_agentsarrayNoAgents with which delegates may run. Empty means any.
yolobooleanNoApproval mode for every delegate.
guardrail_checkstringNostrict, lenient, or off.
asyncbooleanNoWhether compatible API answers return immediately.
wait_secondsintegerNoFrom 1 to 60.
mcp_hintsbooleanNoWhether MCP results end with pending-message and approval counts.
routingobjectNoComplete replacement routing configuration. It can be null.
routing.modestringNooff, suggest, or auto.
routing.lightobjectNoLight worker configuration.
routing.light.modelstringNoLight worker model.
routing.light.thinkingstringNoLight worker thinking setting.
routing.heavyobjectNoHeavy worker configuration.
routing.heavy.modelstringNoHeavy worker model.
routing.heavy.thinkingstringNoHeavy worker thinking setting.
worker_backendstringNollm, acp, or null.
worker_delegated_agentstring | nullNoDelegated agent for an acp worker.
allowed_worker_backendsarray | nullNoBackends a dispatch may name.
worker_delegated_modelstring | nullNoClaude model for an acp delegate.
worker_delegated_effortstringNolow, medium, high, xhigh, max, or null.
worker_modelstring | nullNoModel for an llm delegate when no routing tier applies.
worker_thinkingstringNooff, on, low, medium, high, xhigh, max, or null.
realtime_max_itemsintegerNoMaximum Realtime items, from the larger of 1 and the current usage through 16777216. Default: 1048576.
speechobjectNoComplete 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.

Terminal window
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"
}'

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

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents a change to a different Bot that now holds the same id.
expect_revisionqueryintegerNoThe settings revision that was read. It prevents overwriting newer settings.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
guardrailsstringYesNew limits. An empty string clears the existing guardrails.
Terminal window
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."
}'

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

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents resetting a different Bot that now holds the same id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
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"

Media type: application/json

{
"archived": 30,
"session_id": "c71d0e5a2b9f4a08"
}
NameTypeRequiredDescription
session_idstringYesThe Bot’s new session id.
archivedintegerYesNumber of log rows moved to the archive.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents deleting a different Bot that now holds the same id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
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"

Media type: none

The response has no body.

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.

NameInTypeRequiredDescription
realmquerystringNoRealm whose Bots to resume: global, a 24-hex realm id, or all.
X-Hoody-RealmheaderstringNoRealm whose Bots to resume: global or a 24-hex realm id. The header does not accept all.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/resume?realm=all"

Media type: application/json

{
"resumed": [
{
"id": "chief",
"realm": "global"
}
]
}
NameTypeRequiredDescription
resumedarrayYesBots resumed by this call, in realm and id order.
resumed[].idstringYesThe Bot id.
resumed[].realmstringYesThe Bot’s realm.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
Idempotency-KeyheaderstringNoRetry 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-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
textstringYesMessage text, at most 64 KiB.
Terminal window
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."
}'

Media type: application/json

{
"message_id": "msg-6f1c0e2a-3b9d-4c51-9a7e-2d4b8c1f0a63",
"state": "posted",
"turn_id": "turn-k3x9-4"
}
NameTypeRequiredDescription
message_idstringYesThe accepted message id. Its log row carries this value.
statestringYesposted: 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_idstringNoBot turn that posted the message. Present when state is posted.
reasonstringNoWhen 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).

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
keypathstringYesIdempotency key, from 1 to 255 printable ASCII characters with no whitespace. URL-encode it. It must not begin with compat: or chan:.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
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"

Media type: application/json

{
"message_id": "msg-6f1c0e2a-3b9d-4c51-9a7e-2d4b8c1f0a63",
"state": "posted",
"turn_id": "turn-k3x9-4"
}
NameTypeRequiredDescription
message_idstringYesThe message id.
statestringYesposted: 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_idstringNoBot turn that posted the message. Present when state is posted.
reasonstringNoWhen 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).

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
sincequeryintegerNoReturn rows whose seq is greater than this value. Default: 0.
limitqueryintegerNoMaximum 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.
beforequeryintegerNoRead backward from this sequence. It cannot be combined with since or tail.
tailquerybooleanNoReturn the newest rows, oldest first. It cannot be combined with since or before.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/log?since=0&limit=100&realm=global"

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
}

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
sincequeryintegerNoReturn rows whose seq is greater than this value. Default: 0.
limitqueryintegerNoMaximum 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.
beforequeryintegerNoRead backward from this sequence. It cannot be combined with since or tail.
tailquerybooleanNoNot accepted by the archive route.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/archive?since=0&limit=100&realm=global"

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
}

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
sincequeryintegerNoReturn rows whose seq is greater than this value. Default: 0.
Last-Event-IDheaderstringNoResume cursor containing the last received event id. It overrides since.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
curl -N "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/stream?since=0&realm=global"

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.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents changing a different Bot that now holds the same id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
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"

Media type: application/json

{
"archived": 12
}
NameTypeRequiredDescription
archivedintegerYesNumber of rows moved to the archive.

Deletes the rows that forget and reset moved to the archive. The active log is not changed.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
expect_uidquerystringNoThe Bot uid that was read. It prevents changing a different Bot that now holds the same id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
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"

Media type: application/json

{
"purged": true
}
NameTypeRequiredDescription
purgedbooleanYesAlways true.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
statequerystringNoopen or closed. If omitted, both states are included.
pagequeryintegerNoOne-based page number.
limitqueryintegerNoMaximum items per page. 0 disables pagination.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/delegates?state=open&page=1&limit=20&realm=global"

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

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
sidpathstringYesThe delegate session id.
Idempotency-KeyheaderstringNoOpaque retry key from 1 to 255 printable ASCII characters with no whitespace. It must not begin with chan:.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
closebooleanNoAlso close the delegate session permanently. Default: false.
Terminal window
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
}'

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"
}
NameTypeRequiredDescription
command_idstringYesStop command id.
session_idstringYesDelegate session id.
titlestringYesTitle given by the Bot.
statestringYescommitted or queued.
stoppedarrayYesWork on which the stop acted.
stopped[].kindstringYessession, task, workflow_run, bash_job, or loop.
stopped[].idstringYesId of the stopped work.
stopped[].outcomestringYesstopped, already_done, or failed.
stopped[].detailstringNoWhy a stop failed.
stopped[].cleanupstringNodetached_may_survive when a detached process might still run.
cleanupstringNodetached_may_survive when a detached process might still run.
closedbooleanYesWhether the delegate session was closed.
dropped_messagesintegerNoBot messages dropped because they had not been read.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
turn_idstringYesThe running Bot turn to stop.
Terminal window
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"
}'

Media type: application/json

{
"status": "ok",
"turn_id": "turn-k3x9-4",
"matched": true
}
NameTypeRequiredDescription
statusstringNook when the stop was sent.
turn_idstringNoTurn named by the request.
matchedbooleanNotrue when it was the Bot’s running turn, false when nothing was stopped.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
X-Hoody-RealmheaderstringNoRealm in which to look up the Bot: global or a 24-hex realm id.
realmquerystringNoQuery alias for X-Hoody-Realm. It is read when the header is absent.
NameTypeRequiredDescription
gate_idstringYespending_gate.gate_id from the Bot resource.
generationintegerYespending_gate.generation from the Bot resource.
request_idstringNoYour id for an approval decision, up to 64 characters from A-Z, a-z, 0-9, ., _, and -.
confirmobjectNoDecision for an approval. Exactly one of confirm or answer is required.
confirm.approvedbooleanNotrue approves this call, false refuses it. It is required within confirm.
confirm.reasonstringNoReason for refusing the call. Maximum length: 500.
answerobjectNoAnswer to a question. Exactly one of confirm or answer is required.
answer.answerstringNoNon-blank answer text. It is required within answer.
Terminal window
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
}
}'

Media type: application/json

{
"status": "ok",
"resolved": {},
"replayed": false
}
NameTypeRequiredDescription
statusstringNook when the Bot session consumed the decision.
resolvedobjectNoThe session’s resolution of the gate.
replayedbooleanNotrue when the same answer was sent again after the question accepted it.