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

Agent: Loops

Section titled “Agent: Loops”

Scheduled self-prompting loops let an agent session run a recurring prompt at a fixed interval, with optional budgets, expiry, and pause/resume controls. This page covers the five REST endpoints that list, create, update, delete, and immediately trigger a loop on a session. Use these endpoints whenever you need to manage the lifecycle of recurring agent tasks without going through the streaming command channel.

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

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

Lists the recurring loops scheduled for a session (loops.list). The response uses the standard kit list envelope {items, meta:{total}}. The optional page and limit query parameters window the result set gateway-side; pass limit=0 for the unpaginated full list.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier.
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route.
realmquerystringNoPer-request realm selector — 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 this route.
Terminal window
curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/loops?page=1&limit=20" \
  -H "Authorization: Bearer $HOODY_TOKEN"

POST /api/v1/agent/sessions/{id}/loops

Section titled “POST /api/v1/agent/sessions/{id}/loops”

Creates a recurring loop on a session (loops.create). You supply the prompt fired each run, the run interval, an optional stop predicate, and cost/wall-clock budgets. Loop firings use the dedicated loop lane, not commandChan.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route.
realmquerystringNoPer-request realm selector — 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 this route.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
promptstringYesThe prompt fired each loop run.
intervalstringNoRun interval (duration token, e.g. 30m).
max_runsintegerNoStop after this many runs (0 = unlimited).
stop_whenstringNoOptional stop predicate evaluated each run.
max_cost_usdnumberNoCost ceiling (0 = unlimited).
max_wall_msintegerNoWall-clock ceiling in ms (0 = unlimited).
Terminal window
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/loops" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Check CI status and report failures",
    "interval": "30m",
    "max_runs": 100,
    "max_cost_usd": 5.0,
    "max_wall_ms": 3600000
  }'

POST /api/v1/agent/sessions/{id}/loops/{loopId}/run-now

Section titled “POST /api/v1/agent/sessions/{id}/loops/{loopId}/run-now”

Fires a loop’s next run immediately (loops.run_now). The trigger is dispatched off the dedicated loop lane, so it does not contend with commandChan traffic. The body is optional and carries no defined fields.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier.
loopIdpathstringYesPath identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route.
realmquerystringNoPer-request realm selector — 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 this route.

Request Body

Section titled “Request Body”

Optional. The schema is empty; pass {} or omit. Reserved _-prefixed keys are ignored and the request scope (cwd / config_dir) is applied automatically.

Terminal window
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/loops/{loopId}/run-now" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /api/v1/agent/sessions/{id}/loops/{loopId}

Section titled “PATCH /api/v1/agent/sessions/{id}/loops/{loopId}”

Updates a loop. The body shape selects exactly one intent:

  • paused — run-state intent, dispatched to loops.set_state (true pauses, false resumes).
  • expires_in — expiry intent, dispatched to loops.set_expiry (duration-from-now token, e.g. 2h; empty string or never clears).
  • max_cost_usd and max_wall_ms — budget intent, dispatched to loops.update (sets or revives the cost / wall-clock ceilings).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier.
loopIdpathstringYesPath identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route.
realmquerystringNoPer-request realm selector — 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 this route.

Request Body

Section titled “Request Body”

Set exactly one of the following intents per request.

NameTypeRequiredDescription
pausedbooleanNoRun-state intent — loops.set_state. true pauses, false resumes.
expires_instringNoExpiry intent — loops.set_expiry. Duration-from-now token, e.g. 2h. Empty string or never clears the expiry.
max_cost_usdnumberNoBudget intent — loops.update. Cost ceiling (0 = unlimited).
max_wall_msintegerNoBudget intent — loops.update. Wall-clock ceiling in ms or a duration token (0 = unlimited).
Terminal window
curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/loops/{loopId}" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paused": true
  }'

DELETE /api/v1/agent/sessions/{id}/loops/{loopId}

Section titled “DELETE /api/v1/agent/sessions/{id}/loops/{loopId}”

Deletes a recurring loop from a session (loops.delete). The body is optional and carries no defined fields.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier.
loopIdpathstringYesPath identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route.
realmquerystringNoPer-request realm selector — 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 this route.

Request Body

Section titled “Request Body”

Optional. The schema is empty; pass {} or omit. Reserved _-prefixed keys are ignored and the request scope (cwd / config_dir) is applied automatically.

Terminal window
curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/loops/{loopId}" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'