Skip to content
hannudocs
Get API key
Changelog

Loops

Run a Task or Workflow on a schedule inside a budget you cap — a recurring, killable program that never spends without passing the envelope and your agent's authorize chain.

A Loop is a recurring program. Where a workflow buys one outcome now, a Loop schedules that same order on a cadence — a weekly vendor audit, a monthly rider re-check — inside a budget envelope you cap and can stop at any moment. A Loop never spends at creation, and every run it generates passes two fences before any escrow locks: the budget envelope, and the owning agent's unchanged authorize chain. Managing Loops requires the can_manage_loops delegation flag, and the surface is gated by flags.loop.engine.

Propose-only by default

A newly created Loop launches propose-only: each scheduled run parks for a human decision before it charges. Nothing runs automatically until you deliberately opt in, within your governed bounds. Creation itself moves no money.

POST/v1/estimate_loop

Dry-run a Loop — schedule preview, per-run cost, fundable runs. No state change.

Bearer auth

See the next few run times, what each run costs, and how many runs your budget covers — before you commit anything.

POST/v1/estimate_loop
curl -X POST https://api.hannu.africa/v1/estimate_loop \
  -H "Authorization: Bearer $HANNU_KEY"
POST/v1/loops

Create a recurring program. Requires can_manage_loops. No spend at creation.

Bearer auth

The budget is an integer minor-unit cap across all runs (budget_total_minor); an optional per_run_cap_minor bounds any single run. The Loop is created disarmed and returns the authorized envelope.

POST/v1/loops
curl -X POST https://api.hannu.africa/v1/loops \
  -H "Authorization: Bearer $HANNU_KEY"
{
  "data": {
    "id": "loop_7c31",
    "status": "draft"
  }
}

The schedule is one of: weekly (weekdays[] 1=Mon…7=Sun, hour), interval (interval_hours), monthly (day, hour), or adaptive (interval_hours — the platform tunes only the timing, within your bounds). A Loop moves through draft → active, and paused, capped, exhausted, expired, or killed.

GET/v1/loops

Your Loops — definition, cadence, envelope, status, next run.

Bearer auth
GET/v1/loops/:id

A Loop plus its run history — statuses and spend only, never Operator identities.

Bearer auth
POST/v1/loops/:id/activate

Arm a draft Loop so it runs on its cadence (propose-only).

Bearer auth
POST/v1/loops/:id/pause

Stop scheduling new runs. Non-destructive — the budget is preserved.

Bearer auth
POST/v1/loops/:id/resume

Resume from the next cadence, inside the same envelope.

Bearer auth
POST/v1/loops/:id/cancel

End the Loop for good. Any un-drawn envelope is simply never used.

Bearer auth
The envelope is enforced by the ledger, not the AI

The budget cap is a hard limit checked at the money layer. The platform pauses a Loop before the envelope is exceeded, and each run still escrow-locks per order exactly like a one-off. The AI layer is never in the path of a spend decision. See Escrow and the ledger.

Was this page helpful?