The Agent Tasks endpoints let you inspect and control the background subagent tasks running inside a live session. Use them to ask the session for a snapshot of its current tasks, retrieve an individual task’s transcript from a cursor, cancel a single task mid-turn, or cancel every background task at once. All four endpoints are fire-and-forget from the HTTP side: the gateway returns a short JSON acknowledgment, and the actual task data is delivered on the session’s WS/SSE stream.

Note

Background tasks survive session.cancel but are not restartable. The listTasks and requestTaskTranscript endpoints are snapshot/upsert requests — the HTTP body is a short daemon acknowledgment, and the real tasks_snapshot / task_transcript payload arrives on the session stream, not inline.

List background tasks

Asks a live session to emit its background-subagent task snapshot (session.task_list → event.tasks_snapshot).

GET /api/v1/agent/sessions/{id}/tasks

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request —config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector (§6.1): “global” or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request

cURL

curl -X GET "https://api.hoody.com/api/v1/agent/sessions/507f1f77bcf86cd799439011/tasks" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.agent.tasks.listTasks({
  id: "507f1f77bcf86cd799439011"
});

Response

200

{
  "ok": true,
  "event": "tasks_snapshot"
}

400

{
  "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 an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

429

{
  "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.

500

{
  "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.

503

{
  "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.

Request a task’s transcript

Asks a live session to emit a background task’s transcript from an after_seq cursor (session.task_transcript → event.task_transcript). The transcript arrives on the session’s stream, not inline.

Caution

after_seq is an int64 upsert-poll cursor: the open entry is re-sent at or below the value you supply. It is distinct from the gateway’s int64 stream seq and the daemon’s uint64 log seq, and is not a monotonic replay cursor.

GET /api/v1/agent/sessions/{id}/tasks/{tid}/transcript

Parameters

Name	In	Type	Required	Default	Description
id	path	string	Yes		Path identifier.
tid	path	string	Yes		Path identifier.
after_seq	query	integer	No	0	int64 upsert-poll cursor; entries at/below it are re-sent (default 0).
X-Hoody-Cwd	header	string	No		Per-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No		Per-request —config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No		Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No		Per-request realm selector (§6.1): “global” or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No		Per-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request

cURL

curl -X GET "https://api.hoody.com/api/v1/agent/sessions/507f1f77bcf86cd799439011/tasks/abc123def456abc123def456/transcript?after_seq=42" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.agent.tasks.requestTaskTranscript({
  id: "507f1f77bcf86cd799439011",
  tid: "abc123def456abc123def456",
  after_seq: 42
});

Response

200

{
  "ok": true,
  "event": "task_transcript"
}

400

{
  "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 an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

429

{
  "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.

500

{
  "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.

503

{
  "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.

Cancel a background task

Cancels one background subagent task on a live session (session.task_cancel). The cancel is handled at the server layer, so it works mid-turn. This endpoint does not accept a request body.

POST /api/v1/agent/sessions/{id}/tasks/{tid}/cancel

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
tid	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request —config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector (§6.1): “global” or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request

cURL

curl -X POST "https://api.hoody.com/api/v1/agent/sessions/507f1f77bcf86cd799439011/tasks/abc123def456abc123def456/cancel" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.agent.tasks.cancelTask({
  id: "507f1f77bcf86cd799439011",
  tid: "abc123def456abc123def456"
});

Response

200

{
  "ok": true,
  "cancelled": true
}

400

{
  "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 an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

413

{
  "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 (MaxBodyBytes). The gateway rejects an oversized body at the edge (http.MaxBytesReader) before the handler reads it — a well-formed-but-large body is a size violation, not a JSON syntax error.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

{
  "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.

500

{
  "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.

503

{
  "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.

Cancel all background tasks

Cancels every background subagent task on a live session in one call (session.task_cancel with an empty task id cancels all). This endpoint does not accept a request body.

POST /api/v1/agent/sessions/{id}/tasks/cancel

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request —config-dir override (§6.1) selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector (§6.1): “global” or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request

cURL

curl -X POST "https://api.hoody.com/api/v1/agent/sessions/507f1f77bcf86cd799439011/tasks/cancel" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.agent.tasks.cancelAllTasks({
  id: "507f1f77bcf86cd799439011"
});

Response

200

{
  "ok": true,
  "cancelled_all": true
}

400

{
  "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 an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

413

{
  "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 (MaxBodyBytes). The gateway rejects an oversized body at the edge (http.MaxBytesReader) before the handler reads it — a well-formed-but-large body is a size violation, not a JSON syntax error.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

{
  "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.

500

{
  "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.

503

{
  "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.