---
title: "Request human approval (agent-only)"
method: POST
path: "/v1/approvals/request"
tags: ["Approvals"]
---

# Request human approval (agent-only)

`POST /v1/approvals/request`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/approvals/request`
- Auth: HTTP bearer

Ask a human to approve an action.

Two families of action are accepted:

* the control-plane requests `access_request`, `policy_request`
  and `binding_request`, which widen the agent's own authority; and
* business actions named `namespace.verb` (`refund.create`,
  `social.post`), whose meaning is carried by `summary` and `payload`.

Actions that 1Claw itself executes on approval — `policy_change`,
`card_order`, `agent_transaction`, `agent_execution`,
`agent_sign_intent` — are created by the platform and rejected here,
because the summary a human reads would be agent-supplied while the
side effect would not be.

## Request body

- object
  - `action` string, required: Control-plane action, or a business action named `namespace.verb`.
  - `target_type` string, required
  - `target_id` string, required
  - `summary` object, required: What the human is shown: title, body, and key-value fields.
  - `payload` object: What the action will actually do. The enforced risk tier and the human-readable line are derived from this, not from `summary` — the two can disagree, and only this one describes what happens if the human approves.
  - `reason` string
  - `declared_risk_tier` integer: Advisory. The server derives the enforced tier from the agent's `action_approval_policy` and the payload, then takes the higher of the two: a caller may raise its own bar, never lower it. The response returns both.
  - `risk_tier` integer: Former name for `declared_risk_tier`. Still accepted.

## Response `202`

Approval request created

- ApprovalResponse
  - `id` string, uuid, required
  - `org_id` string, uuid, required
  - `user_id` string, uuid, required
  - `agent_id` string, uuid, nullable
  - `action` string, required
  - `target_type` string, required
  - `target_id` string, required
  - `risk_tier` integer, required: The tier actually enforced. Authoritative.
  - `declared_risk_tier` integer, nullable: What the caller asked for, when it asked for anything.
  - `declared_below_floor` boolean: The caller asked for a lower tier than policy required.
  - `human_summary` string, nullable: Plain-language line sent to SMS, push and email.
  - `payload` object: What the action will do, as submitted.
  - `status` 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled', required
  - `summary` object, required: Structured summary of the action requiring approval
  - `reason` string, nullable
  - `decision_reason` string, nullable
  - `decided_by` string, uuid, nullable
  - `decided_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `created_at` string, date-time, required

## Other responses

- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)