HITL Approvals

When a require_approval policy matches, the MeshAI proxy blocks the request and queues it for human review. An authorized user must approve or deny each request before the agent can proceed.

How It Works

Agent Request → MeshAI Proxy → Policy Engine
                                    ↓
                        require_approval matched?
                           ↓              ↓
                          Yes             No
                           ↓              ↓
                    Return 403      Forward to LLM
                    + queue item
                           ↓
                   Dashboard Queue
                           ↓
                  Approve / Deny
                           ↓
                  Cache decision in Redis (TTL)
                           ↓
                  Agent retries → Approved → Forward to LLM

Request blocked

The proxy evaluates policies and finds a require_approval match. The request is blocked with a 403 status and an approval item is created.

Queued for review

The approval item appears in the MeshAI dashboard under Governance → Approvals. It includes the agent, the policy that triggered the block, and the request context.

Human decides

An authorized user reviews the item and submits a decision of approved or denied, identifying themselves as the reviewer. They can add a reason for the decision.

Decision cached

Approved decisions are cached in Redis so the agent does not need re-approval on every request. The approval request itself carries an expiry (default TTL: 24 hours).

Agent retries

The agent retries the request. The proxy checks the Redis cache, finds the approval, and forwards the request to the LLM provider.

The 403 Response

When a request requires approval, the agent receives:

{
  "error": "approval_required",
  "approval_policy_id": 42
}

Approval Statuses

Status	Meaning
`pending`	Queued, waiting for a human decision
`approved`	Approved - agent can retry
`denied`	Denied - agent request will continue to be blocked
`expired`	TTL elapsed without a decision

List Pending Approvals

curl https://api.meshai.dev/api/v1/approvals?status=pending \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

from meshai import MeshAI

client = MeshAI(api_key="msh_...")
pending = client.list_approvals(status="pending")

{
  "success": true,
  "data": [
    {
      "id": 17,
      "policy_id": 42,
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "team_id": null,
      "request_context": { "provider": "openai", "model": "gpt-4o" },
      "status": "pending",
      "expires_at": "2026-03-18T10:30:00Z",
      "resolved_at": null,
      "created_at": "2026-03-17T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50 }
}

Approve or Deny

curl -X POST https://api.meshai.dev/api/v1/approvals/17/decide \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "user@company.com",
    "decision": "approved",
    "reason": "Verified agent configuration is correct"
  }'

curl -X POST https://api.meshai.dev/api/v1/approvals/17/decide \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "user@company.com",
    "decision": "denied",
    "reason": "Agent not authorized for production use yet"
  }'

# Approve
client.decide_approval(17, reviewer_id="user@company.com", decision="approved", reason="Verified")

# Deny
client.decide_approval(17, reviewer_id="user@company.com", decision="denied", reason="Not authorized")

reviewer_id is required (1-100 characters) and decision must be approved or denied; reason is optional.

Cache TTL

When an approval is granted, the decision is cached in Redis so the agent does not need re-approval on every subsequent matching request. The approval request’s expiry defaults to 24 hours from creation - there is currently no per-policy field to override this default.

Getting Started

Proxy (Zero-Code)

Framework Guides

Governance

EU AI Act Compliance

Billing

How It Works

The 403 Response

Approval Statuses

List Pending Approvals

Approve or Deny

Cache TTL

​How It Works

​The 403 Response

​Approval Statuses

​List Pending Approvals

​Approve or Deny

​Cache TTL

How It Works

The 403 Response

Approval Statuses

List Pending Approvals

Approve or Deny

Cache TTL