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 gate parks a turn until it is answered. Use these endpoints to list question and confirm gates, answer them, request answer suggestions, and manage a session’s approval mode, lock, permission rules, and YOLO auto-approve state.

In the Hub, open the chat and answer its waiting approval with Allow once or Deny. To change its approval mode, open Details, Session, Approvals and choose Default or Strict while the chat is idle; Auto-approve is in the same section.

Lists the gates waiting for a human. The response covers the same sessions visible to GET /api/v1/agent/sessions, including each live session’s own gate and, for a helper_gates session, its helpers’ gates.

A gate is listed only while this gateway holds its session live. A session held only by another client is not listed until it is attached here. Bot runtime gates, including bot.dispatch, bot.peek, and bot.answer_gate frames, are answered by the Bot runtime and are not listed or counted.

Each item contains the daemon’s redacted gate description. A gate that resolves or changes while the list is being read is omitted and counted in meta.omitted. Results are ordered by oldest parked first, then session_id, then generation.

The realm query parameter selects one realm, and realm=all selects every realm served by the login. A computer header is not supported. The response uses Cache-Control: no-store.

NameInTypeRequiredDescription
include_systemquerybooleanNoWhen true, also list gates from daemon-owned system and resident sessions.
realmquerystringNoRealm to list: "global", a 24-hex realm id, or "all" for every realm served by the login. Also accepted through X-Hoody-Realm, except for "all".
pagequeryintegerNo1-based page number. An invalid page is a 400 bad_request.
limitqueryintegerNoMaximum items per page. An omitted or zero limit, or a value above 100, is served as 100. meta.limit echoes the value used.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-RealmheaderstringNoPer-request realm selector: "global" or a 24-hex realm id.
Terminal window
curl --get 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/gates' \
--data-urlencode 'include_system=false' \
--data-urlencode 'realm=global' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=50'
FieldTypeRequiredDescription
itemsarrayYesPending gates returned on this page.
items[].session_idstringNoSession that owns the gate.
items[].realmstringNoSession realm.
items[].gate_idstringNoAnswerable gate id.
items[].generationintegerNoGateway’s gate generation.
items[].kindstringNoGate kind: confirm or question.
items[].helper_idstringNoHelper that parked the gate.
items[].parent_tool_call_idstringNoLead tool call that started the helper.
items[].task_idstringNoBackground helper task id.
items[].agentstringNoSession agent.
items[].parked_atstringNoRFC3339 time the gateway parked the gate.
items[].rulesobjectNoTool-call rules that asked for the gate.
items[].gateobjectNoDaemon’s redacted gate description.
metaobjectYesPagination metadata.
meta.totalintegerNoNumber of gates parked when the list was read, across all pages.
meta.pageintegerNo1-based page served.
meta.limitintegerNoPage size used, at most 100.
meta.omittedintegerNoGates that changed or resolved during the read and were left out.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"items": [
{
"agent": "builder",
"gate": {
"gate_cause": "rules",
"gate_id": 3,
"generation": 0,
"human_only": false,
"lease_required": false,
"params": {
"command": "git push origin main"
},
"risk": "unknown",
"rules": {
"outcome": "ask",
"rule_ids": [
"ask-git"
]
},
"status": "parked",
"tool_name": "bash",
"type": "confirm"
},
"gate_id": "gate-9f2c4e1ab07d3355-3",
"generation": 3,
"kind": "confirm",
"parked_at": "2026-09-28T10:15:04.512Z",
"realm": "global",
"rules": {
"outcome": "ask",
"rule_ids": [
"ask-git"
]
},
"session_id": "9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55"
}
],
"meta": {
"limit": 100,
"omitted": 0,
"page": 1,
"total": 1
}
}

Returns the session’s effective approval policy, including the default or always mode, monotonic lock, policy revision, waiver posture, session permission rules, and approver lease state.

The response ETag is the policy revision. Send that value as If-Match when updating the policy. event.permission_rules frames on the event stream are snapshots of the same rule set. Each frame follows a successful durable write, so clients should converge on the frame contents rather than assume that the frame acknowledges their own request.

This endpoint works for live and persisted sessions and returns Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesSession id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
Terminal window
curl 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval' \
-H 'X-Hoody-Realm: global'
FieldTypeRequiredDescription
modestringNoEffective mode: default or always.
lockedbooleanNoWhether the policy is frozen for the session lifetime.
revisionintegerNoMonotonic policy revision and ETag value.
yolobooleanNoWhether YOLO auto-approve is armed.
auto_writebooleanNoWhether automatic file-write permission is on.
auto_dir_accessbooleanNoWhether automatic directory access is on.
backend_auto_approvingbooleanNoWhether a delegated backend auto-approves its own tools.
rulesarrayNoSession permission rules.
rules[].toolstringYesTool name or tool:action rule key.
rules[].decisionstringYesRule decision: allow or deny.
leaseobjectNoApprover lease state. The capability itself is not returned.
epochstringNoOpaque daemon execution epoch.
changedbooleanNoWhether an update changed anything.
capabilitiesobjectNoApproval features supported by the daemon.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"mode": "default",
"locked": false,
"revision": 3,
"yolo": false,
"auto_write": false,
"auto_dir_access": false,
"backend_auto_approving": false,
"rules": [
{
"tool": "bash",
"decision": "deny"
}
],
"lease": {},
"epoch": "epoch-7f3a",
"capabilities": {}
}

GET /api/v1/agent/sessions/{id}/rules/applies

Section titled “GET /api/v1/agent/sessions/{id}/rules/applies”

Returns the tool-call rules that a live session checks for one agent’s calls. The selection matches the rule checker: a rule without tools skips read-only tools, a rule with tools covers only those tools, and a rule with agents covers only those agents’ calls.

The agent parameter defaults to the session’s own agent. The tool parameter limits the checked rules to the rules sent for that call. Without tool, the response includes every checked rule that covers the agent’s calls to at least one tool. Guidance and playbook rules are also returned with applies_as: prompt, and count includes both checked and prompt rules.

A rule’s when value is a list of condition atoms. Each atom starts with + or - and names tools, for example +edit_file|write_file or -bash(command=go test):success. It is not a prose condition.

fail_closed_reason indicates when all covered calls currently fail closed. A dormant session returns 404 not_found. The response uses Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesSession id.
agentquerystringNoAgent to ask about. Defaults to the session’s own agent.
toolquerystringNoTool to ask about. Defaults to any tool.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
Terminal window
curl --get 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/rules/applies' \
--data-urlencode 'agent=builder' \
--data-urlencode 'tool=bash' \
-H 'X-Hoody-Realm: global'
FieldTypeRequiredDescription
agentstringNoAgent whose calls were evaluated.
toolstringNoTool named in the request.
read_onlybooleanNoWhether the named tool is read-only.
activebooleanNoWhether the session checks any covering rules.
countintegerNoNumber of checked and prompt rules.
rulesarrayNoRules that apply to the agent, in settings order.
rules[].idstringNoRule id.
rules[].textstringNoRule in plain words.
rules[].kindstringNoRule kind: limit, check_in, guidance, or playbook.
rules[].applies_asstringNochecked or prompt.
rules[].toolsarrayNoTools covered by the rule.
rules[].agentsarrayNoAgents covered by the rule.
rules[].whenarrayNoRule condition atoms.
rules[].sourcestringNoSettings file that declared the rule.
rules[].scopestringNoSettings scope: user, project, or local.
rules[].folderstringNoFolder associated with a project or local rule.
prompt_offbooleanNoWhether the team-rules prompt block is disabled.
prompt_bytesintegerNoSize of the rule lines included in the prompt.
prompt_budget_bytesintegerNoMaximum prompt size, 8192 bytes.
prompt_over_budgetarrayNoCovered prompt rules excluded by the byte budget.
prompt_over_budget[].idstringNoRule id.
prompt_over_budget[].textstringNoRule in plain words.
prompt_over_budget[].kindstringNoRule kind: limit, check_in, guidance, or playbook.
prompt_over_budget[].applies_asstringNochecked or prompt.
prompt_over_budget[].toolsarrayNoTools covered by the rule.
prompt_over_budget[].agentsarrayNoAgents covered by the rule.
prompt_over_budget[].whenarrayNoRule condition atoms.
prompt_over_budget[].sourcestringNoSettings file that declared the rule.
prompt_over_budget[].scopestringNoSettings scope: user, project, or local.
prompt_over_budget[].folderstringNoFolder associated with a project or local rule.
fail_closed_reasonstringNotrust_hold, jev_disabled, or jev_no_key when every covered call fails closed.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"agent": "builder",
"tool": "bash",
"read_only": false,
"active": true,
"count": 1,
"rules": [
{
"id": "ask-bash",
"text": "Ask before running bash commands.",
"kind": "check_in",
"applies_as": "checked",
"tools": [
"bash"
],
"agents": [],
"source": "settings.json",
"scope": "project",
"folder": "/workspace/project"
}
],
"prompt_off": false,
"prompt_bytes": 41,
"prompt_budget_bytes": 8192,
"prompt_over_budget": []
}

Answers a parked question gate. Send answer or text for a free-form response, or answers for a structured multi-field question. A body with none of these values is rejected and the question stays parked.

For a workflow question with options, answer must name one option case-insensitively. text carries the input for an option that accepts user input. Any other option name is rejected with 400 bad_request, and the question remains parked.

A retry that names an already answered question with the same answer receives the original acknowledgement. A different answer receives 409 gate_already_answered and is not applied. If the turn was cancelled while the answer was in flight, the endpoint returns 409 gate_cancelled; the answer was not applied and must not be retried.

NameInTypeRequiredDescription
idpathstringYesSession id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
gate_idstringNoEcho of the parked gate id. A mismatch is 409 stale_gate.
generationintegerNoEcho of the parked gate generation.
answerstringNoFree-form answer text. If blank, text is used instead. A view frame request accepts a JSON-encoded view object.
textstringNoAnswer text used when answer is absent or blank. For an option with user input, this is the option’s input.
answersobjectNoMap of structured per-field answers. Each value is a string.
Terminal window
curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/answer' \
-H 'Content-Type: application/json' \
-H 'X-Hoody-Realm: global' \
--data '{
"gate_id": "gate-9f2c4e1ab07d3355-3",
"generation": 3,
"answer": "Use the staging environment."
}'
FieldTypeRequiredDescription
statusstringNo"ok" on success.
resolvedobjectNoDaemon’s gate resolution.
replayedbooleanNoWhether the response replays an earlier acknowledgement.
session_scope_appliedbooleanNoWhether a session-wide grant could not be applied.
notestringNoExplanation accompanying session_scope_applied.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"status": "ok",
"resolved": {
"outcome": "answered"
},
"replayed": false
}

POST /api/v1/agent/sessions/{id}/answer:assist

Section titled “POST /api/v1/agent/sessions/{id}/answer:assist”

Runs a one-shot helper-model call that proposes answers for a parked question. The proposal is published through event.question_suggestion; it is not applied to the gate. The real answer must still be sent to POST /api/v1/agent/sessions/{id}/answer.

The endpoint returns a job id immediately. Fetch the completed result from GET /api/v1/agent/jobs/{id}/result. Only one assist job can run for a session at a time. If the session’s realm is not usable by the login, the assist is refused before it starts. A refusal discovered after the 202 fails the job with the corresponding error code.

NameInTypeRequiredDescription
idpathstringYesSession id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
modestringNo"suggest"Suggestion mode.
modelstringNoHelper model override. An empty value uses the configured helper.
genintegerNoGeneration counter echoed as event.question_suggestion.gen.
Terminal window
curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/answer:assist' \
-H 'Content-Type: application/json' \
-H 'X-Hoody-Realm: global' \
--data '{
"mode": "suggest",
"gen": 1
}'
FieldTypeRequiredDescription
job_idstringNoGateway-minted id for the helper job.
session_idstringNoSession whose parked question is being answered.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"job_id": "job-7f3a2d9c",
"session_id": "9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55"
}

Approves or denies a parked tool or directory confirmation. A 200 means the agent consumed this exact decision. A gate that was already answered, cancelled, timed out, auto-approved by YOLO, or ended with an earlier connection returns 409 gate_already_resolved, and the submitted decision was not applied.

A decision whose outcome is not known returns 409 gate_decision_pending. Retry the same decision with the gate id to learn its outcome. 409 no_pending_gate means nothing is parked, and 409 stale_gate means the supplied gate id or generation does not name the parked gate. A decision without gate_id is rejected when several confirm gates are parked.

NameInTypeRequiredDescription
idpathstringYesSession id.
X-Hoody-Approver-LeaseheaderstringNoApprover lease capability. Required on decisions for an always session after its lease has been minted.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
gate_idstringNoEcho of the parked gate id. Required on an always session.
generationintegerNoEcho of the parked gate generation. Required and nonzero on an always session.
approvedbooleanYestrue approves the call. false denies it.
reasonstringNoDenial reason, at most 500 characters. Accepted only with approved: false.
persist_dirsbooleanNoPersist an approved directory grant to settings.json.
rememberbooleanNoWith approval, false applies only to this call. Omitted or true may allow later changes to the same file.
supersededbooleanNoDeclines the call because the user sent a new message instead of answering.
session_scopebooleanNoRemembers the decision for the rest of the session. Only offer it when the gate permits a session-wide allowance.
trust_computerbooleanNoAccepts the gate’s execution trust offer.
request_idstringNoCaller’s decision id, at most 64 characters from A-Z, a-z, 0-9, ., _, and -.
lease_generationintegerNoApprover lease generation under which the decision was made.
Terminal window
curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/confirm' \
-H 'Content-Type: application/json' \
-H 'X-Hoody-Realm: global' \
-H 'X-Hoody-Approver-Lease: approver-lease-capability' \
--data '{
"gate_id": "gate-9f2c4e1ab07d3355-3",
"generation": 3,
"approved": true,
"remember": false,
"request_id": "ui-7f3a"
}'
  • client.agent.gates.approve(id, data, options?) sets approved to true.
  • client.agent.gates.deny(id, data, options?) sets approved to false.
FieldTypeRequiredDescription
statusstringNo"ok" on success.
resolvedobjectNoDaemon’s gate resolution that consumed the decision.
session_scope_appliedbooleanNoWhether a session-wide grant could not be applied.
notestringNoExplanation accompanying session_scope_applied.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"status": "ok",
"resolved": {}
}

Changes the session’s approval mode and lock. Send If-Match with the ETag returned by GET /api/v1/agent/sessions/{id}/approval to make the change conditional. * or an absent If-Match makes the request unconditional. An omitted body field keeps its current value.

The always mode requires an explicit decision for each side-effecting invocation, including bash, writes and deletes, non-GET web_fetch, fleet actions, non-read-only MCP tools, image generation, and notifications. memory_save, todo mutators, and propose_cron_entry remain ungated. Reads, grep, glob, and task tools are never gated.

Under always, executors that cannot park a decision are refused, including subagents, workflow runs and resumes, the orchestrator, foreign CLIs, run_todo, and test_hook. Configured hook commands are skipped and disclosed, configured MCP servers are not started, and stdin to a background bash process is refused. Machine-confirmed execution paths that perform side effects are also refused, while reads continue.

Switching to always arms the approver lease requirement but does not mint a lease. Every later decision must present an acquired lease and name the exact gate_id and generation. See Holding the right to answer a session’s gates for the approver lease.

The lock freezes the mode and all waiver aliases for the session lifetime. It is monotonic and cannot be removed. The policy can change only when the session is idle. A stale If-Match returns 412, a locked policy returns 409 approval_policy_locked, an unsupported mode returns 409 approval_policy_unsatisfiable, and a busy session returns 409 session_busy.

NameInTypeRequiredDescription
idpathstringYesSession id.
If-MatchheaderstringNoETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
modestringNoApproval mode: default or always. Omit to keep the current mode.
lockedbooleanNoFreezes the policy for the session lifetime. Omit to keep the current lock.
Terminal window
curl -X PUT 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval' \
-H 'Content-Type: application/json' \
-H 'If-Match: "3"' \
-H 'X-Hoody-Realm: global' \
--data '{
"mode": "always",
"locked": true
}'
FieldTypeRequiredDescription
modestringNoEffective mode: default or always.
lockedbooleanNoWhether the policy is frozen for the session lifetime.
revisionintegerNoNew monotonic policy revision and ETag value.
yolobooleanNoWhether YOLO auto-approve is armed.
auto_writebooleanNoWhether automatic file-write permission is on.
auto_dir_accessbooleanNoWhether automatic directory access is on.
backend_auto_approvingbooleanNoWhether a delegated backend auto-approves its own tools.
rulesarrayNoSession permission rules.
rules[].toolstringYesTool name or tool:action rule key.
rules[].decisionstringYesRule decision: allow or deny.
leaseobjectNoApprover lease state. The capability itself is not returned.
epochstringNoOpaque daemon execution epoch.
changedbooleanNoWhether the request changed anything.
capabilitiesobjectNoApproval features supported by the daemon.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"mode": "always",
"locked": true,
"revision": 4,
"yolo": false,
"auto_write": false,
"auto_dir_access": false,
"backend_auto_approving": false,
"rules": [
{
"tool": "bash",
"decision": "deny"
}
],
"lease": {},
"epoch": "epoch-7f3a",
"changed": true,
"capabilities": {}
}

PUT /api/v1/agent/sessions/{id}/approval/rules/{tool}

Section titled “PUT /api/v1/agent/sessions/{id}/approval/rules/{tool}”

Upserts one session permission rule for tool. Send one object, not an array. A deny rule is always accepted. An allow rule is refused with 409 approval_policy_locked on a locked policy and 409 approval_policy_active under always, because allow rules are not consulted there.

Send If-Match with the current policy ETag to make the change conditional. A stale value returns 412 and the response carries the current ETag. Successful writes emit event.permission_rules and event.approval_policy_changed.

The write is durable or nothing. If the durable write fails, the rule is rolled back and no policy events are broadcast. Every event.permission_rules frame therefore carries persisted rules. The frame remains a snapshot to converge on, not proof that the request that produced it succeeded.

NameInTypeRequiredDescription
idpathstringYesSession id.
toolpathstringYesTool whose permission rule is being set.
If-MatchheaderstringNoETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
decisionstringYesPermission decision: allow or deny.
Terminal window
curl -X PUT 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval/rules/bash' \
-H 'Content-Type: application/json' \
-H 'If-Match: "3"' \
-H 'X-Hoody-Realm: global' \
--data '{
"decision": "deny"
}'
FieldTypeRequiredDescription
statusstringNo"ok" on success.
rulesarrayNoFull session permission-rule set after the change.
rules[].toolstringYesTool name or tool:action rule key.
rules[].decisionstringYesRule decision: allow or deny.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"status": "ok",
"rules": [
{
"tool": "bash",
"decision": "deny"
}
]
}

Turns the session’s YOLO auto-approve state on or off. This is the same capability as the TUI’s YOLO toggle. A caller that can reach this endpoint is treated as having permission to perform the requested change.

Arming YOLO is refused with 409 approval_policy_locked on a locked policy and 409 approval_policy_active under always. Disarming YOLO remains permitted under either policy. The response contains the applied yolo state, and the change emits event.yolo_mode.

NameInTypeRequiredDescription
idpathstringYesSession id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
NameTypeRequiredDefaultDescription
enabledbooleanYestrue arms auto-approve. false disarms it.
Terminal window
curl -X PATCH 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/yolo' \
-H 'Content-Type: application/json' \
-H 'X-Hoody-Realm: global' \
--data '{
"enabled": true
}'
  • client.agent.sessions.disableYolo(id, data, options?) sets enabled to false.
  • client.agent.sessions.enableYolo(id, data, options?) sets enabled to true.
FieldTypeRequiredDescription
statusstringNo"ok" on success.
yolobooleanNoApplied auto-approve state.
forwardedbooleanNoWhether the command was delivered without an acknowledgement within the wait.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"status": "ok",
"yolo": false,
"forwarded": false
}

DELETE /api/v1/agent/sessions/{id}/approval/rules/{tool}

Section titled “DELETE /api/v1/agent/sessions/{id}/approval/rules/{tool}”

Clears the session permission rule for tool, restoring the per-call prompt for that tool. The operation is refused with 409 approval_policy_locked when the policy is locked.

Send If-Match with the current policy ETag to make the removal conditional. A stale value returns 412 and the response carries the current ETag. Successful writes emit event.permission_rules and event.approval_policy_changed.

The write is durable or nothing. If the durable write fails, the removal is rolled back and no policy events are broadcast. Every event.permission_rules frame therefore carries persisted rules. The frame remains a snapshot to converge on, not proof that the request that produced it succeeded.

NameInTypeRequiredDescription
idpathstringYesSession id.
toolpathstringYesTool whose permission rule is being removed.
If-MatchheaderstringNoETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. The value must be valid UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. The value must be valid UTF-8.
X-Hoody-ComputerheaderstringNoBound remote computer. Omit for the local computer.
X-Hoody-RealmheaderstringNoSession realm selector: "global" or a 24-hex realm id.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted.
Terminal window
curl -X DELETE 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval/rules/bash' \
-H 'If-Match: "3"' \
-H 'X-Hoody-Realm: global'
FieldTypeRequiredDescription
statusstringNo"ok" on success.
rulesarrayNoFull session permission-rule set after the removal.
rules[].toolstringYesTool name or tool:action rule key.
rules[].decisionstringYesRule decision: allow or deny.

Error responses use code and message, with an optional details object.

Media type: application/json

{
"status": "ok",
"rules": []
}