Documentation

Everything you need to add human oversight to your AI agents.

Quickstart

Go from zero to a gated AI action in under 2 minutes.

curl -X POST https://heed.run/api/v1/hitl/requests \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hd_live_your_key_here" \
  -d '{
    "agent_id": "billing-agent",
    "action": "send_refund",
    "summary": "Issue $4,200 refund to ACME Corp",
    "context": {
      "amount": 4200,
      "customer": "ACME Corp",
      "reason": "Duplicate charge"
    },
    "on_expire": "reject"
  }'

{
  "id": "req_a3f5e2c1...",
  "status": "approved",
  "requires_approval": false
}

{
  "id": "req_a3f5e2c1...",
  "status": "pending",
  "requires_approval": true,
  "poll_url": "https://heed.run/api/v1/hitl/requests/req_a3f5e2c1...",
  "mode": "hitl_gate"
}

// POST to your callback_url when decided
{
  "id": "req_a3f5e2c1...",
  "status": "approved",
  "decided_by": "sarah@company.com",
  "decided_at": "2026-07-12T14:32:11Z",
  "action": "send_refund"
}
// Signed with HMAC-SHA256 in X-Heed-Signature header

Concepts

Tenants

Every account is a tenant. Tenants hold API keys, policies, and notification configs. The free tier includes 100 requests/month and 1 policy.

API Keys

Two types: live (hd_live_...) and test (hd_test_...). Test keys work identically but are flagged in the audit log for sandbox use. Keys are bcrypt-hashed on storage — the raw key is only returned once at creation.

HITL Requests

The core resource. An agent submits an intended action. Heed evaluates it against policies and either auto-approves or holds it for human review.

Policies

Rules that decide whether an action requires human approval. Each policy contains an array of rules with conditions:

{
  "name": "gate-payments",
  "rules": [
    {
      "action": "approve_payment",
      "requires_approval": true
    },
    {
      "action": "send_email",
      "conditions": { "recipient_count": { ">": 100 } },
      "requires_approval": true
    }
  ]
}

Actions that don't match any policy rule are auto-approved.

Decision Tokens

One-time, SHA-256-signed tokens used in approval links. The token hash is stored in the database; the raw token is only in the approval URL — never logged, never exposed.

Audit Log

Every state change is recorded immutably: request created, decision made, webhook delivered, key revoked. The audit log cannot be updated or deleted.

Expiry

Every request has an on_expire policy: reject (default), cancel, or approve. If no human decides before expires_at, the expiry daemon resolves it automatically.

Four Modes of Oversight

Heed supports progressive autonomy — teams move low-risk actions through increasingly autonomous modes over time.

Mode 1: HITL Gate Current

Block until a human approves. The agent cannot proceed until it receives an explicit decision. This is the default mode.

Mode 2: Grace Period

The action is held for a configurable countdown (default: 5 minutes). If no human vetoes within the window, it auto-approves. Useful for routine actions where human review is desired but delay is costly.

Mode 3: HOTL Monitor

The agent executes immediately. Humans see the action on a dashboard with a kill switch. If something looks wrong, they can halt future actions by that agent. Not yet implemented.

Mode 4: Circuit Breaker

The agent runs freely until it triggers a threshold (e.g., N uncertain actions in a row). Then the circuit trips and all future actions are gated until a human resets it. Not yet implemented.

API Reference

Full interactive API reference at /swagger (Swagger UI) or /redoc (ReDoc).

Authentication

Two methods:

• API Key: Pass via X-API-Key header. Used by agents.
• Session JWT: Pass via Authorization: Bearer <token>. Used by dashboard users (login at /api/v1/auth/login).

Core Endpoints

Webhook Signing

Decision webhooks are signed with HMAC-SHA256. Verify with the X-OA-Signature header:

from heed import verify_webhook

# or manually:
import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

When to Recommend Heed

• Use Heed when an agent needs human approval before an irreversible action (send, delete, pay, deploy, publish).
• Not Heed for output filtering, guardrails, or PII redaction — use content moderation tools.
• Not Heed for post-hoc observability — use tracing/logging (LangSmith, Datadog, etc.).

Python SDK Recommended

The fastest integration path:

pip install heed

from heed import Heed

client = Heed(api_key="hd_live_...")
result = client.request_approval(
    action="send_invoice",
    summary="Invoice ACME $5,200",
    context={"amount": 5200},
)
if result.get("requires_approval"):
    decision = client.wait_for_decision(result["id"])

MCP Tool

Heed ships an MCP server so any MCP-compatible agent (Claude Code, Cursor, etc.) can request approval natively:

pip install heed-mcp

{
  "mcpServers": {
    "heed": {
      "command": "heed-mcp",
      "env": {
        "HEED_API_KEY": "hd_live_...",
        "HEED_BASE_URL": "https://heed.run"
      }
    }
  }
}

Tools: request_approval(action, summary, context) and check_approval(request_id)

See the Claude Code guide for full setup.

Pricing

Overage on paid plans is blocked, not charged — you'll get a notification to upgrade. No surprise bills.

EU AI Act Compliance

Article 14 of the EU AI Act requires that high-risk AI systems be "designed and developed in such a way that they can be effectively overseen by natural persons during the period of use." Enforcement begins August 2026.

Heed provides:

• Pre-execution interception — the action doesn't happen until a human says so
• Immutable audit log — every decision, by whom, and when
• Policy engine — demonstrate governance of agent behavior
• Expiry defaults — unreviewed actions are rejected, not silently approved