👤Human-in-the-Loop•POST /v1/checkpoints

Human-in-the-Loop

Pause an agent and wait for human approval before continuing.

What it does

Creates an approval gate that pauses execution until a human approves, rejects, or modifies the proposed action.

Endpoint

Method: POST

Path: POST /v1/checkpoints

Auth: x-agent-id + x-api-key

Request shape

•title: string
•callback_url: string
•timeout_action?: string
•timeout_seconds?: number

Example requests

Copy-pasteable examples for agents and automation.

cURL

curl -X POST https://www.agent-utils.com/v1/checkpoints \
  -H "x-agent-id: finance-bot" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "title": "Approve wire transfer?",
    "callback_url": "https://your-server.com/resume",
    "timeout_action": "auto_reject",
    "timeout_seconds": 3600
  }'

Python

import requests

resp = requests.post(
    "https://www.agent-utils.com/v1/checkpoints",
    headers={
        "x-agent-id": "finance-bot",
        "x-api-key": "agutil_agt_…",
        "content-type": "application/json",
    },
    json={
        "title": "Approve wire transfer?",
        "callback_url": "https://your-server.com/resume",
        "timeout_action": "auto_reject",
        "timeout_seconds": 3600,
    },
)
checkpoint_id = resp.json()["data"]["id"]

JavaScript

const res = await fetch("https://www.agent-utils.com/v1/checkpoints", {
  method: "POST",
  headers: {
    "x-agent-id": "finance-bot",
    "x-api-key": "agutil_agt_…",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    title: "Approve wire transfer?",
    callback_url: "https://your-server.com/resume",
    timeout_action: "auto_reject",
    timeout_seconds: 3600,
  }),
});
const { data } = await res.json();

How agents use it

A finance agent pauses before sending a wire transfer and resumes only after approval.

An editor reviews a drafted article before publication.

An operations agent asks for approval before deleting data or closing an account.

When to use it

✓An agent is about to perform an irreversible or high-cost action.
✓You need human sign-off for compliance or safety reasons.
✓The agent is confident but the business impact is too high to automate completely.

When not to use it

•The action is low risk and should never block the workflow.
•You need pure automation with no human review path.

Failure modes

•If the callback URL is wrong, the agent cannot resume.
•Timeout behaviour must be defined or the workflow can hang indefinitely.
•High-friction approvals should be reserved for genuinely risky steps.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "checkpoint",
  "title": "Human-in-the-Loop",
  "canonical": "/docs/checkpoint",
  "endpoint": "POST /v1/checkpoints",
  "method": "POST",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "title: string",
    "callback_url: string",
    "timeout_action?: string",
    "timeout_seconds?: number"
  ],
  "agent_workflows": [
    "A finance agent pauses before sending a wire transfer and resumes only after approval.",
    "An editor reviews a drafted article before publication.",
    "An operations agent asks for approval before deleting data or closing an account."
  ],
  "failure_modes": [
    "If the callback URL is wrong, the agent cannot resume.",
    "Timeout behaviour must be defined or the workflow can hang indefinitely.",
    "High-friction approvals should be reserved for genuinely risky steps."
  ]
}

Related docs

audit-log dlq