Agent: Todos

File, read, update, claim, run, snooze, and archive agent todos. Approve or deny run proposals, run an LLM triage pass over the inbox, and purge archived rows. Write operations are CAS-guarded by the per-todo revision (fetched from getTodo); the store-wide revision from getTodosRevision is a cheap poll cursor, not a CAS token.

The agent routes are scoped by the request’s working directory (the .hoody project layer / record cwd / tool+workflow cwd) via the X-Hoody-Cwd header (or a body cwd on create). Per-request realm scoping is rejected with realm_scope_unsupported on these routes.

List and read

`GET /api/v1/agent/todos`

Lists master todos for the requesting cwd/config_dir, with a store-wide revision poll cursor. Typed filters ride the request body — there is no query-param filter alias.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos?page=1&limit=25" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{"open_only": true, "tags": ["P0", "security"]}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.listTodosIterator({ open_only: true, tags: ["P0", "security"] }, { page: 1, limit: 25 });

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias of `X-Hoody-Realm`). Rejected on this route.

Request body

Optional typed filters forwarded to todos.list. All fields are optional; omit the body for the full list.

Name	Type	Required	Description
`states`	array of string	No	Filter to these todo states.
`tags`	array of string	No	Filter to todos carrying these tags.
`query`	string	No	Free-text filter over title/body.
`open_only`	boolean	No	When true, only open (non-terminal) todos.
`all`	boolean	No	When true, include archived/closed todos.

Responses

{
  "items": [
    {
      "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
      "title": "Rotate staging TLS certs",
      "body": "STAGING cluster certs expire in 14 days.",
      "state": "open",
      "priority": 1,
      "tags": ["security", "P1"],
      "revision": 7,
      "created_at": "2026-01-04T09:00:00Z",
      "updated_at": "2026-01-12T14:32:10Z"
    },
    {
      "id": "todo_01HMZX8T2B6K1M5N7P9RWDEFGH",
      "title": "Refactor billing idempotency keys",
      "state": "in_progress",
      "priority": 2,
      "tags": ["billing"],
      "revision": 3,
      "created_at": "2026-01-05T11:20:00Z",
      "updated_at": "2026-01-13T08:05:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 25
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

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

Returns the full todo record including timeline and proposals (todos.read).

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.getTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE');

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias of `X-Hoody-Realm`). Rejected on this route.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "title": "Rotate staging TLS certs",
  "body": "STAGING cluster certs expire in 14 days.",
  "state": "open",
  "priority": 1,
  "rank": 0,
  "tags": ["security", "P1"],
  "revision": 7,
  "proposals": [
    {
      "id": "prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ",
      "kind": "run",
      "summary": "Run certbot renew on staging nodes",
      "status": "pending",
      "created_at": "2026-01-12T14:00:00Z"
    }
  ],
  "timeline": [
    {
      "kind": "comment",
      "text": "Filed by on-call.",
      "at": "2026-01-04T09:00:00Z"
    },
    {
      "kind": "message",
      "text": "Started investigate.",
      "at": "2026-01-12T14:00:00Z"
    }
  ],
  "created_at": "2026-01-04T09:00:00Z",
  "updated_at": "2026-01-12T14:32:10Z"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

`GET /api/v1/agent/todos/revision`

Returns the store-wide revision counter (todos.revision) — a cheap poll cursor that moves on every persisted mutation. This is NOT the per-todo CAS token; updateTodo, archiveTodo, snoozeTodo, and claimTodo take each todo’s own revision from getTodo.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/revision" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.getTodosRevision();

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Responses

{
  "revision": 1284
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

Create and update

`POST /api/v1/agent/todos`

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

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rotate staging TLS certs",
    "body": "STAGING cluster certs expire in 14 days.",
    "priority": 1,
    "tags": ["security", "P1"]
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.createTodo({
  title: "Rotate staging TLS certs",
  body: "STAGING cluster certs expire in 14 days.",
  priority: 1,
  tags: ["security", "P1"]
});

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (defaults the body `cwd` when omitted).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`title`	string	Yes	Todo title.
`body`	string	No	Todo body / description.
`priority`	integer	No	Optional priority band 0..4 (0 = P0 urgent … 4 = P4 someday); defaults to 2 when omitted. Must be a JSON integer in range.
`tags`	array of string	No	Optional tags.
`cwd`	string	No	The todo’s working directory. Defaults to the `X-Hoody-Cwd` header when omitted.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "deduped": false,
  "revision": 1
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Applies a CAS-guarded field patch / state transition to a todo (todos.update). Pass the current revision from getTodo; a stale revision is rejected.

cURL
TypeScript SDK

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": 7,
    "state": "in_progress",
    "priority": 0
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.updateTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', {
  revision: 7,
  state: "in_progress",
  priority: 0
});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`revision`	integer	Yes	The todo’s own current `revision` (from `getTodo` — NOT the store-wide revision).
`title`	string	No	New title.
`body`	string	No	New body.
`state`	string	No	New state transition.
`priority`	integer	No	New priority.
`rank`	integer	No	New ordering rank.
`tags`	array of string	No	New tag set.
`cwd`	string	No	Retarget the todo’s working directory.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "revision": 8,
  "updated_at": "2026-01-13T09:15:00Z"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "todo_conflict",
  "message": "todo_conflict: revision mismatch (refetch and retry)"
}

Error Code	Title	Description	Resolution
`todo_conflict`	Todo revision conflict	The supplied revision is stale (a concurrent update advanced the todo).	GET the todo (getTodo) for its current `revision` — the per-todo CAS token, NOT the store-wide `getTodosRevision` — and re-issue the update.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Archives a todo (todos.archive). The body carries the CAS revision from getTodo.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/archive" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{"revision": 7}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.archiveTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', { revision: 7 });

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`revision`	integer	Yes	The todo’s own current `revision` (from `getTodo`).

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "state": "archived",
  "revision": 8
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Snoozes a todo until a wake time (todos.snooze). The body carries the RFC3339 wake_at and the CAS revision.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/snooze" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{
    "wake_at": "2026-07-04T09:00:00Z",
    "revision": 7
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.snoozeTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', {
  wake_at: "2026-07-04T09:00:00Z",
  revision: 7
});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`wake_at`	string	Yes	Wake time, RFC3339 (e.g. `2026-07-04T09:00:00Z`); an empty string clears the snooze.
`revision`	integer	Yes	The todo’s own current `revision` (from `getTodo`).

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "wake_at": "2026-07-04T09:00:00Z",
  "revision": 8
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`POST /api/v1/agent/todos/purge`

Permanently and irreversibly removes archived todos (todos.purge). An empty body purges all archived tombstones for the cwd.

cURL
TypeScript SDK

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.purgeTodos({});

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional filter object forwarded to todos.purge. An empty body purges all archived tombstones for the cwd. No fields are documented.

Responses

{
  "purged": 14
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability so its own gate allows HTTP requests forwarded from the gateway.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Comments and messages

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

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

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/messages" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{"text": "Investigating — looks like certs are also stale on node-3."}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.postTodoComment('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', { text: "Investigating — looks like certs are also stale on node-3." });

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`text`	string	Yes	The comment body to append to the todo timeline.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "revision": 8,
  "message_id": "msg_01HN0ABCDEF1234567890ABCDE"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Posts a comment AND kicks an orchestrator turn on the todo (todos.message). 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 (getTodo) for the orchestrator’s reply/proposal on the timeline; a succeeded job means the turn was dispatched, not finished.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/message" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{"text": "Please draft a run plan for the cert rotation, then post a proposal."}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.messageTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', { text: "Please draft a run plan for the cert rotation, then post a proposal." });

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`text`	string	Yes	The message that both comments and prompts the orchestrator.

Responses

{
  "job_id": "job_01HN0Z9K8Q5WX2AB3CD4EFGHJK"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Claim, release, run, and cancel

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

Claims a todo for the caller (todos.claim). The CAS revision is required for a fresh claim; only the lease’s existing owner may refresh without it.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/claim" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{"revision": 7}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.claimTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', { revision: 7 });

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

Name	Type	Required	Description
`revision`	integer	No	The todo’s own current `revision` (from `getTodo`). Required for a fresh claim; only the lease’s existing owner may refresh without it.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "lease_owner": "agent_01HN0LEASEOWNER1234567890",
  "lease_expires_at": "2026-01-13T13:00:00Z",
  "revision": 8
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Releases a claimed todo (todos.release).

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/release" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.releaseTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', {});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.release RPC. No fields are documented.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "lease_owner": null,
  "revision": 9
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Dispatches a background worker to autonomously work a todo (todos.run) and returns {job_id, session_id}. The daemon treats reaching the todos.run RPC as the human approval itself (“issued by the TUI Run action or the CLI, both human-driven”). 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 (getTodo) — it lands in review when the worker is done.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/run" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.runTodo('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', {});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.run RPC. No fields are documented.

Responses

{
  "job_id": "job_01HN0Z9K8Q5WX2AB3CD4EFGHJK",
  "session_id": "sess_01HN0RUNNER1234567890ABCDE"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability so its own gate allows HTTP requests forwarded from the gateway.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Cancels an in-flight orchestrator run for a todo (todos.cancel_run).

cURL
TypeScript SDK

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.cancelTodoRun('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', {});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.cancel_run RPC. No fields are documented.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "state": "open",
  "run_cancelled": true,
  "revision": 10
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Proposals

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

Approves a run proposal on a todo (todos.approve_proposal). Approval is NOT inert: the daemon hands the approved proposal to a background worker session equivalent to todos.run — a J-class autonomous run. (The paired denyTodoProposal spawns no worker.)

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/proposals/prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ/approve" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.approveTodoProposal('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', 'prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ', {});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`pid`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.approve_proposal RPC. No fields are documented.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "proposal_id": "prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ",
  "status": "approved",
  "job_id": "job_01HN0Z9K8Q5WX2AB3CD4EFGHJK",
  "session_id": "sess_01HN0RUNNER1234567890ABCDE"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability so its own gate allows HTTP requests forwarded from the gateway.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

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

Denies a run proposal on a todo (todos.deny_proposal). No worker is spawned.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/todos/todo_01HMZX7P5V3J8N9K4Q2WXABCDE/proposals/prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ/deny" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /home/user/projects/acme" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.denyTodoProposal('todo_01HMZX7P5V3J8N9K4Q2WXABCDE', 'prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ', {});

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`pid`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.deny_proposal RPC. No fields are documented.

Responses

{
  "id": "todo_01HMZX7P5V3J8N9K4Q2WXABCDE",
  "proposal_id": "prop_01HMZZ1QAE3V6X8K2B4NMD0FHJ",
  "status": "denied"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Triage

`POST /api/v1/agent/todos/triage`

Kicks an LLM triage pass over the inbox (todos.triage) and returns {job_id}. This is a J-class op: it spends model budget on an autonomous LLM run — the same property that makes todos.run a privileged op.

cURL
TypeScript SDK

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.todos.triageTodos({});

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Per-request realm selector (query alias). Rejected on this route.

Request body

The body is an optional JSON object forwarded to the daemon todos.triage RPC. An empty body triages the whole inbox. No fields are documented.

Responses

{
  "job_id": "job_01HN0TRIAGE1234567890ABCDEF"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a route that has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability so its own gate allows HTTP requests forwarded from the gateway.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.