Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: Todos

Section titled “Agent: Todos”

File, read, update, claim, run, snooze, archive, and purge agent todos. Approve or deny run proposals, post comments, run an LLM triage pass over the inbox, and manage the lease lifecycle. The agent routes live under /api/v1/agent/todos on the agent service inside a container.

List and read

Section titled “List and read”

GET /api/v1/agent/todos

Section titled “GET /api/v1/agent/todos”

List todos. Lists master todos for the requesting cwd / config-dir, with the store-wide poll-cursor revision (a change-detection cursor for the whole list, NOT the per-todo CAS token; todos.update, todos.archive, todos.snooze, and todos.claim take each todo’s own revision from client.agent.todos.get()). Filter with the query parameters states, tags (repeat the parameter for several values), query, open_only, and all. An invalid boolean or unknown state is a 400. The result is open todos first, then by priority, rank, and number (the default order), or closed todos by closed_at newest first when sort=closed_at.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
statesqueryarrayNoOnly todos in one of these states. Repeat the parameter for several (?states=ready&states=blocked).
tagsqueryarrayNoOnly todos carrying these tags. Repeat the parameter for several (?tags=a&tags=b).
queryquerystringNoFree-text filter over title and body.
open_onlyquerybooleanNoWhen true, only open (non-terminal) todos.
allquerybooleanNoWhen true, include archived and closed todos.
sortquerystringNoList order. default (or omitted): open todos first, then priority, rank, number. closed_at: closed todos by closed_at, newest first; todos without a closed_at follow in the default order. Any other value is 400.
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
realmquerystringNoThe realm to list: “global” (todos not tied to a realm), a 24-hex realm id, or “all” for every realm this login serves. Also accepted as the X-Hoody-Realm header, except “all”. Omitted, the agent’s current realm.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos?open_only=true&tags=ops&page=1&limit=20' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Authorization: Bearer <token>'

GET /api/v1/agent/todos/{id}

Section titled “GET /api/v1/agent/todos/{id}”

Read a todo. Returns the full todo record including its timeline and any pending proposals.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Authorization: Bearer <token>'

GET /api/v1/agent/todos/revision

Section titled “GET /api/v1/agent/todos/revision”

Get the todos store revision. Returns the store-wide revision counter, a cheap poll cursor that moves on every persisted mutation. Use it for change detection over the whole list. It is NOT the per-todo CAS token used by updates.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/revision' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Authorization: Bearer <token>'

Create

Section titled “Create”

POST /api/v1/agent/todos

Section titled “POST /api/v1/agent/todos”

File a todo. Files a new master todo. Deterministic triage (normalize, fingerprint-dedupe, defaults) runs server-side. The todo’s working directory is taken from the body cwd, or from the X-Hoody-Cwd request-scope header when the body field is omitted; one of the two is required.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope. Required when the body omits cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
titlestringYesTodo title.
bodystringNoTodo body / description.
priorityintegerNoOptional priority band 0..4 (0 = P0 urgent, 4 = P4 someday); defaults to 2 when omitted. Must be a JSON integer in range; a string or out-of-range value is rejected.
tagsarray of stringsNoOptional tags.
cwdstringNoThe todo’s working directory. Defaults to the X-Hoody-Cwd request-scope header when omitted; one of the two must be set.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "title": "Rotate the staging credentials",
    "body": "Swap the staging IAM access keys this week.",
    "priority": 1,
    "tags": ["ops"]
  }'

Update

Section titled “Update”

PATCH /api/v1/agent/todos/{id}

Section titled “PATCH /api/v1/agent/todos/{id}”

Update a todo (CAS). Applies a CAS-guarded field patch or state transition to a todo. Pass the current revision; a stale revision is rejected (the 409 todo_conflict path). Only the keys present in the body are patched.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
revisionintegerYesThe todo’s own current revision (from client.agent.todos.get(), NOT the store-wide revision). A stale value is rejected.
titlestringNoNew title.
bodystringNoNew body.
statestringNoNew state transition.
priorityintegerNoNew priority.
rankintegerNoNew ordering rank.
tagsarray of stringsNoNew tag set.
cwdstringNoRetarget the todo’s working directory.
Terminal window
curl -X PATCH 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "revision": 8,
    "priority": 0,
    "state": "ready"
  }'

Lifecycle transitions

Section titled “Lifecycle transitions”

POST /api/v1/agent/todos/{id}/archive

Section titled “POST /api/v1/agent/todos/{id}/archive”

Archive a todo. Marks the todo as archived. Pass the current revision; a stale revision is rejected.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
revisionintegerYesThe todo’s own current revision (from client.agent.todos.get()). Required; a stale or absent value is rejected.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/archive' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{ "revision": 8 }'

POST /api/v1/agent/todos/{id}/snooze

Section titled “POST /api/v1/agent/todos/{id}/snooze”

Snooze a todo. Snoozes a todo until a wake time. Pass an empty string in wake_at to clear an existing snooze.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
wake_atstringYesWake time, RFC3339 (for example 2026-07-04T09:00:00Z); an empty string clears the snooze.
revisionintegerYesThe todo’s own current revision (from client.agent.todos.get()); a stale value is rejected.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/snooze' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "wake_at": "2026-07-04T09:00:00Z",
    "revision": 8
  }'

Lease and runs

Section titled “Lease and runs”

POST /api/v1/agent/todos/{id}/claim

Section titled “POST /api/v1/agent/todos/{id}/claim”

Claim a todo. Takes the execution lease on a todo and moves it to in_progress. session_id is the lease owner and is required: it is the identity every later guard compares against, so the same value must come back on todos.release, and a second caller claiming under a different session_id is refused while the lease is live. Pass the todo’s own revision for a fresh claim; the lease’s current owner may re-claim without one to refresh the TTL idempotently. run_id is free-form correlation the lease carries for you. The lease belongs to the daemon that minted it; another daemon’s live lease is never taken over.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
session_idstringYesIdentity that will OWN the lease; required and non-empty. todos.release must present the same value; while the lease is live another session_id cannot claim the todo.
run_idstringNoOptional correlation id recorded on the lease (for example the run this claim belongs to); not an identity, it is never used for ownership checks.
revisionintegerNoThe todo’s own current revision (from client.agent.todos.get()). Conditionally required: a fresh claim (no live lease, or a lease held by another session_id) must carry it; omitted means revision 0 and the CAS refuses the claim (409 todo_conflict). The lease’s current owner re-claiming to refresh its TTL may omit it.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/claim' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "session_id": "sess_01HMZXEXAMPLE",
    "run_id": "run_01HMZXEXAMPLE",
    "revision": 8
  }'

POST /api/v1/agent/todos/{id}/release

Section titled “POST /api/v1/agent/todos/{id}/release”

Release a todo. Ends the run holding a todo’s lease and records the outcome. session_id must be the same value todos.claim leased under; the daemon refuses a release from any other session, and refuses one on a todo with no active lease. outcome is required and decides the resulting state: done moves the todo to review, blocked moves it to blocked, failed moves it to ready and counts against the attempt cap, cancelled moves it to ready without counting an attempt (so a closed or abandoned run never disqualifies the todo). summary and question_for_human are appended to the timeline and are capped at 1024 characters each.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
session_idstringYesThe session that owns the lease; required, and must match the value todos.claim leased under. A mismatch is refused.
outcomestringYesHow the run ended. One of done, blocked, failed, cancelled. done moves the todo to review; blocked to blocked; failed to ready and increments the attempt counter; cancelled to ready without incrementing it. Required; any other value is rejected.
summarystringNoShort account of what the run did, written to the timeline as the run_end entry (capped at 1024 characters).
question_for_humanstringNoA question to surface to the operator alongside the outcome; the field a blocked run uses to say what it needs (capped at 1024 characters).
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/release' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "session_id": "sess_01HMZXEXAMPLE",
    "outcome": "done",
    "summary": "Rotated the staging IAM keys and verified the deploy."
  }'

POST /api/v1/agent/todos/{id}/run

Section titled “POST /api/v1/agent/todos/{id}/run”

Run a todo’s orchestrator. Dispatches a background worker to autonomously work a todo and returns {job_id, session_id}. The request itself counts as the human approval and no further confirmation is asked; the model-facing run_todo tool, by contrast, refuses an autonomous caller. The minted job completes at DISPATCH (it carries the worker session_id for correlation, but the resident worker runs asynchronously and is NOT tracked by the job lifecycle): a succeeded job means the run was started, not that the todo is finished. Poll the todo itself (client.agent.todos.get()); it lands in review when the worker is done.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

The body is an optional JSON object. Every _-prefixed key is ignored (removed before dispatch), the request scope (cwd / config-dir) is added from the scope headers, and all other keys are passed through verbatim. The todo {id} comes from the path.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/run' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'

POST /api/v1/agent/todos/{id}/cancel-run

Section titled “POST /api/v1/agent/todos/{id}/cancel-run”

Cancel a todo’s run. Cancels an in-flight orchestrator run for a todo.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

No body fields are read; the todo {id} comes from the path. An optional JSON object is accepted.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/cancel-run' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'

Proposals

Section titled “Proposals”

POST /api/v1/agent/todos/{id}/proposals/{pid}/approve

Section titled “POST /api/v1/agent/todos/{id}/proposals/{pid}/approve”

Approve a todo proposal. Approves a run proposal on a todo. Approval is NOT inert: the daemon starts the approved proposal as a background worker session equivalent to client.agent.todos.start(), an autonomous run that spends model budget and asks for no human confirmation. The paired todos.denyProposal spawns no worker.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
pidpathstringYesProposal identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

No body fields are read; the todo {id} and proposal {pid} come from the path. An optional JSON object is accepted.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/proposals/prop_01HMZXEXAMPLE/approve' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'

POST /api/v1/agent/todos/{id}/proposals/{pid}/deny

Section titled “POST /api/v1/agent/todos/{id}/proposals/{pid}/deny”

Deny a todo proposal. Denies a run proposal on a todo. No worker is spawned.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
pidpathstringYesProposal identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

No body fields are read; the todo {id} and proposal {pid} come from the path. An optional JSON object is accepted.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/proposals/prop_01HMZXEXAMPLE/deny' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'

Conversation

Section titled “Conversation”

POST /api/v1/agent/todos/{id}/message

Section titled “POST /api/v1/agent/todos/{id}/message”

Comment + run an orchestrator turn. Posts a comment AND kicks an orchestrator turn on the todo. Returns {job_id}, but the job completes at DISPATCH: the orchestrator runs as a daemon-managed resident whose turn is NOT tracked by the job lifecycle. Poll the todo itself (client.agent.todos.get()) for the orchestrator’s reply or proposal on the timeline; a succeeded job means the turn was dispatched, not finished.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
textstringYesThe message that both comments and prompts the orchestrator.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/message' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "text": "Please rotate the staging IAM keys today and confirm."
  }'

POST /api/v1/agent/todos/{id}/messages

Section titled “POST /api/v1/agent/todos/{id}/messages”

Comment on a todo. Posts a comment onto a todo’s timeline WITHOUT triggering an orchestrator turn. Use /message (singular) to also kick an orchestrator turn.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTodo identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
textstringYesThe comment body to append to the todo timeline.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_3f9a1c7e5b2d4086a1c3e5f7/messages' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{
    "text": "FYI: the new key rotation policy takes effect Monday."
  }'

Admin

Section titled “Admin”

POST /api/v1/agent/todos/purge

Section titled “POST /api/v1/agent/todos/purge”

Purge archived todos. Permanently and irreversibly removes archived todos; the tombstones are destroyed at once, with no confirmation step. The optional body filters which archived todos to purge; an empty body removes archived todos older than the 90-day retention age across every realm, keeping more recently archived ones.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

The body is an optional JSON object. Every _-prefixed key is ignored (removed before dispatch), the request scope (cwd / config-dir) is added from the scope headers, and all other keys are passed through verbatim. With an empty body, archived todos older than the 90-day retention age are removed across every realm.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/purge' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'

POST /api/v1/agent/todos/triage

Section titled “POST /api/v1/agent/todos/triage”

Run an LLM triage pass. Kicks an LLM triage pass over the inbox and returns {job_id}. It spends model budget on an autonomous LLM run and asks for no human confirmation, the same property that makes client.agent.todos.start() a privileged operation. With an empty body the whole inbox is triaged.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

The body is an optional JSON object. Every _-prefixed key is ignored (removed before dispatch), the request scope (cwd / config-dir) is added from the scope headers, and all other keys are passed through verbatim. Optional triage scoping; an empty body triages the whole inbox.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/triage' \
  -H 'X-Hoody-Cwd: /home/user/projects/my-app' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  --data '{}'