Approvals

v0.1.0

When AI reaches the edge of its authority, humans decide. Review, approve, or reject with full audit trail.

Python

bash

pip install human-sdk

List

List approvals with pagination and optional filters. Returns pending, approved, rejected, and expired approvals matching the given filters. Results are ordered by creation time (newest first).

Parameter	Description
`filters`	Optional filters and pagination

python

// First page of pending approvals
const page1 = await client.approvals.list({
  status: 'pending',
  limit: 20
});

// Next page
const page2 = await client.approvals.list({
  status: 'pending',
  limit: 20,
  cursor: page1.next_cursor
});

// Filter by type and risk level
const critical = await client.approvals.list({
  type: 'deployment',
  risk_level: 'critical'
});

Returns: Paginated list of approvals

Get

Get approval details by ID. Retrieves the full approval record including context, risk level, and decision metadata (if decided).

Parameter	Description
`id`	Approval ID

python

const approval = await client.approvals.get('appr_123');
console.log(approval.action_summary);
console.log(approval.risk_level);

Returns: Approval details

Errors

NotFoundError — If approval doesn't exist

AuthorizationError — If not authorized to view approval

Approve

Approve a pending approval request. Transitions the approval status from 'pending' to 'approved', unblocking the gated action for execution. The approver's identity and reasoning are always recorded for audit traceability.

Parameter	Description
`id`	Approval ID
`reason`	Optional reason for approving (recommended for audit trail)

python

const approved = await client.approvals.approve(
  'appr_123',
  'Reviewed action parameters — safe to proceed'
);
console.log(approved.status); // 'approved'
console.log(approved.decided_at); // timestamp

Returns: Updated approval with status 'approved'

Errors

NotFoundError — If approval doesn't exist

AuthorizationError — If not authorized to approve

ConflictError — If approval is not in 'pending' status

Reject

Reject a pending approval request. Transitions the approval status from 'pending' to 'rejected', permanently blocking the gated action. Rejections are final, and the reason is recorded for audit traceability.

Parameter	Description
`id`	Approval ID
`reason`	Optional reason for rejecting (recommended for audit trail)

python

const rejected = await client.approvals.reject(
  'appr_123',
  'Action scope too broad — please narrow to specific resource'
);
console.log(rejected.status); // 'rejected'

Returns: Updated approval with status 'rejected'

Errors

NotFoundError — If approval doesn't exist

AuthorizationError — If not authorized to reject

ConflictError — If approval is not in 'pending' status

Respond

Respond to a pending approval with a rich decision. Supports all decision types: approve, approve with modifications, reject, delegate, and override.

Parameter	Description
`id`	Approval ID
`decision`	Decision payload

python

// Approve with modified parameters
await client.approvals.respond('appr_123', {
  decision: 'approved_with_modifications',
  reason: 'Approved with reduced amount',
  modified_params: { amount: 5000 },
});

// Delegate to another approver
await client.approvals.respond('appr_123', {
  decision: 'delegated',
  delegate_to: 'did:human:sarah',
  reason: 'Sarah handles financial approvals',
});

Returns: Updated approval

Send Message

Send a message in the approval's conversation. Creates a conversational exchange with the agent about the approval. The agent responds immediately with contextual guidance based on the escalation context (risk factors, alternatives, cost estimates).

Parameter	Description
`id`	Approval ID
`content`	Message content

python

const { agent_response } = await client.approvals.sendMessage(
  'appr_123',
  'Why does this need $50,000?'
);
console.log(agent_response.content);

Returns: Human message and agent response

Get Messages

Get conversation history for an approval. Returns all messages in the approval's conversation, ordered chronologically.

Parameter	Description
`id`	Approval ID

Returns: List of messages

Types

python

interface Approval {
  /** Unique approval ID */
  id: string;
  /** Type of action being approved */
  type: ApprovalType;
  /** Current approval status */
  status: ApprovalStatus;
  /** Passport ID of the entity that requested approval */
  requester_id: string;
  /** Passport ID of the human who decided (set on approval/rejection) */
  approver_id?: string;
  /** Human-readable summary of the action awaiting approval.  Generated by the requesting agent to give the approver sufficient context to make an informed decision. */
  action_summary: string;
  /** Risk level of the requested action.  Determines escalation urgency, approver routing, and expiration window per the platform's safety escalation policy. */
  risk_level: ApprovalRiskLevel;
  /** Structured context for the approval request.  Contains machine-readable details about the action, such as affected resources, parameters, and scope. Approvers and audit systems use this for traceability. */
  context: Record<string, unknown>;
  /** Escalation schema for UI rendering.  JSON Schema with UI hints that the approval component uses to auto-render the context panel. Templates (financial, deployment, etc.) provide pre-built schemas; custom escalations can define their own.  When present, the `<human-approval-view>` component renders structured fields with appropriate formatting (currency, badges, lists, etc.) instead of raw JSON. */
  escalation_schema?: Record<string, unknown>;
  /** Conversation ID for the approval's HITL conversation */
  conversation_id?: string;
  /** Modified parameters (set when approved_with_modifications) */
  modified_params?: Record<string, unknown>;
  /** Passport ID of delegate (set when delegated) */
  delegated_to?: string;
  /** Override action description (set when overridden) */
  override_action?: string;
  /** Reason provided by the approver when deciding (approve or reject) */
  decision_reason?: string;
  /** When this approval request was created */
  created_at: Timestamp;
  /** When the decision was made (set on approval/rejection) */
  decided_at?: Timestamp;
  /** When this approval request expires.  If no decision is made by this time, status transitions to 'expired'. Expiration windows are determined by risk level. */
  expires_at: Timestamp;
}

interface ApprovalDecision {
  /** Decision type */
  decision: ApprovalDecisionType;
  /** Optional reason for the decision (recommended for audit trail) */
  reason?: string;
  /** Modified parameters (for approved_with_modifications) */
  modified_params?: Record<string, unknown>;
  /** Passport ID to delegate to (for delegated) */
  delegate_to?: string;
  /** Override action description (for overridden) */
  override_action?: string;
}

interface ApprovalListFilters {
  /** Filter by approval status */
  status?: ApprovalStatus;
  /** Filter by approval type */
  type?: ApprovalType;
  /** Filter by risk level */
  risk_level?: ApprovalRiskLevel;
}