Public beta

Approval API quickstart

Four calls. One durable approval.

Submit one immutable action, let a human approve or reject it, then retrieve the same decision after your workflow restarts.

01 / 04

Submit an exact proposal

POST/api/v1/proposals

curl -X POST https://agenthail.com/api/v1/proposals \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: 2bb7c286-c76f-4e7a-838d-c2c47c4799ac" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_run_id": "n8n_run_2048",
    "tool": "stripe",
    "action_type": "create_refund",
    "arguments": {
      "invoice_id": "INV-2048",
      "amount": 12500,
      "currency": "USD"
    },
    "target": {
      "type": "invoice",
      "id": "INV-2048",
      "version": "7"
    },
    "summary": "Refund invoice INV-2048",
    "policy": {
      "version": "refunds-v3",
      "reference": "policy://billing/refunds"
    },
    "expires_at": "2026-08-01T18:00:00Z"
  }'

201 response · save the token and resume reference

{
  "proposal_id": "req_...",
  "state": "proposed",
  "version": 1,
  "proposal_version": 1,
  "payload_hash": "...",
  "resume_reference": "ahrsm_...",
  "requester_token": "ahr_...",
  "status_url": "https://agenthail.com/api/v1/proposals/req_...",
  "receipt_url": "https://agenthail.com/api/v1/proposals/req_.../receipt"
}

02 / 04

Poll after a restart

GET/api/v1/proposals/:proposal_id

curl https://agenthail.com/api/v1/proposals/req_... \
  -H "X-AgentHail-Request-Token: ahr_..."

03 / 04

Approve or reject

POST/api/v1/proposals/:proposal_id/decision

curl -X POST https://agenthail.com/api/v1/proposals/req_.../decision \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: 5b85f496-cff6-490a-b64e-09be487163ee" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "expected_version": 1,
    "message": "Approved for this exact invoice and amount."
  }'

04 / 04

Retrieve the receipt

GET/api/v1/proposals/:proposal_id/receipt

curl https://agenthail.com/api/v1/proposals/req_.../receipt \
  -H "X-AgentHail-Request-Token: ahr_..."

Agent Log API v0.1

Record what happened after approval

After an exact proposal is approved, create an execution with the approved payload hash and append retry-safe evidence events. Use a private 32-128 character Idempotency-Key for every mutation.

Create an execution

POST/api/v1/proposals/:proposal_id/executions

curl -X POST https://agenthail.com/api/v1/proposals/req_.../executions \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: 9ac258c4-64f2-48dc-8a81-654d871e8311" \
  -H "Content-Type: application/json" \
  -d '{
    "proposal_payload_hash": "APPROVED_PROPOSAL_HASH",
    "attempt_number": 1,
    "provider": "mock-provider",
    "provider_operation_id": "mock-op-2048"
  }'

Record running

POST/api/v1/executions/:execution_id/events

curl -X POST https://agenthail.com/api/v1/executions/exe_.../events \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: c2485060-3895-4d38-a984-1b1153509494" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "execution_started",
    "occurred_at": "2026-07-22T20:00:00Z",
    "reported_by": "n8n",
    "attempt_number": 1,
    "provider": "mock-provider",
    "provider_operation_id": "mock-op-2048",
    "evidence": {"phase":"dispatch_started"}
  }'

Record an unknown outcome

POST/api/v1/executions/:execution_id/events

curl -X POST https://agenthail.com/api/v1/executions/exe_.../events \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: 1ee08ae4-752b-4d8c-a167-3a70c18f65d7" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "execution_unknown",
    "occurred_at": "2026-07-22T20:00:05Z",
    "reported_by": "mock-provider-adapter",
    "attempt_number": 1,
    "provider": "mock-provider",
    "provider_operation_id": "mock-op-2048",
    "evidence": {"timeout_ms":5000,"result":"ambiguous"},
    "raw_receipt": {"transport_result":"timeout_after_dispatch"},
    "error_code": "PROVIDER_TIMEOUT",
    "error_message": "The provider result is unclear."
  }'

Record reconciliation evidence

POST/api/v1/executions/:execution_id/events

curl -X POST https://agenthail.com/api/v1/executions/exe_.../events \
  -H "Authorization: Bearer ah_live_..." \
  -H "Idempotency-Key: 11fa3aa8-e2f7-4cba-8ac7-3d74f0626fd2" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "execution_reconciled",
    "occurred_at": "2026-07-22T20:05:00Z",
    "reported_by": "provider-status-check",
    "attempt_number": 1,
    "provider": "mock-provider",
    "provider_operation_id": "mock-op-2048",
    "evidence": {"observed_outcome":"succeeded"},
    "raw_receipt": {"provider_status":"succeeded"}
  }'

Retrieve the timeline

GET/api/v1/executions/:execution_id

curl https://agenthail.com/api/v1/executions/exe_... \
  -H "Authorization: Bearer ah_live_..."

Retrieve a whole run with GET /api/v1/agent-runs/:agent_run_id. AgentHail stores reported evidence and raw receipts from your workflow. It does not independently verify or execute external actions.

Download the mock timeout workflow

Frozen proposal

Tool, arguments, target, policy, and expiry are hashed and immutable. Approval applies only to that exact payload.

Retry-safe commands

Use a private random Idempotency-Key for creation and decisions. Reuse the same key only when retrying the same command.

Receipt, not execution

The receipt proves what AgentHail authorized or rejected. It does not prove that Stripe, Gmail, Jira, or another provider executed the action.

MCP access

Thin adapter, same proposal service.

Configure the Streamable HTTP endpoint at https://agenthail.com/api/mcp with your API key as a Bearer token. It exposes create, get, wait-for-decision status, and receipt tools only.

{
  "url": "https://agenthail.com/api/mcp",
  "headers": {
    "Authorization": "Bearer ah_live_..."
  }
}

n8n compatibility

Built-in HTTP nodes are enough.

The reference flow submits once, waits persistently, polls after restart, retrieves the receipt, and passes only the original frozen arguments to a mock action.

Download the reference workflow

Stable errors

Conflicts are explicit and machine-readable.

Error responses use {"error":{"code":"...","message":"...","details":{}}}. Handle idempotency_conflict, proposal_version_conflict, proposal_expired, and proposal_already_decided without blindly retrying a changed command.

Release boundary

AgentHail provides durable human authorization. It is not an external execution engine, OAuth broker, workflow orchestrator, reconciliation layer, or exactly-once execution system.