Approvals

Request human approval (agent-only)

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.

post/v1/approvals/request

Request

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

Request body

actionstring required

Control-plane action, or a business action named namespace.verb.

target_typestring required
target_idstring required
summaryobject required

What the human is shown: title, body, and key-value fields.

payloadobject

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.

reasonstring
declared_risk_tierinteger

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_tierinteger

Former name for declared_risk_tier. Still accepted.

Example request

{
  "action": "refund.create",
  "summary": {
    "title": "Refund $49.99",
    "body": "Order #1234 arrived damaged."
  },
  "payload": {
    "amount_usd": "49.99",
    "customer_email": "a.user@example.com"
  }
}

Response

Approval request created

idstring uuid required
org_idstring uuid required
user_idstring uuid required
agent_idstring uuid nullable
actionstring required
target_typestring required
target_idstring required
risk_tierinteger required

The tier actually enforced. Authoritative.

declared_risk_tierinteger nullable

What the caller asked for, when it asked for anything.

declared_below_floorboolean

The caller asked for a lower tier than policy required.

human_summarystring nullable

Plain-language line sent to SMS, push and email.

payloadobject

What the action will do, as submitted.

status'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled' required
summaryobject required

Structured summary of the action requiring approval

reasonstring nullable
decision_reasonstring nullable
decided_bystring uuid nullable
decided_atstring date-time nullable
expires_atstring date-time nullable
created_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.