DocumentationAgent Action Firewall
GitHub

Approvals API

Manage approval workflows for actions requiring human review.

List Pending Approvals

Get all actions awaiting approval.

HTTP
GET /v1/approvals?status=pending

Query Parameters

ParameterTypeDescription
statusstringpending, approved, denied
agent_idstringFilter by agent
risk_levelstringlow, medium, high, critical
limitintegerMax results (default: 20)

Response

JSON
{
  "data": [
    {
      "id": "apr_xyz789",
      "action_id": "act_abc123",
      "status": "pending",
      "action": {
        "tool": "http_proxy",
        "operation": "DELETE",
        "params": {
          "url": "https://api.company.com/customers/123"
        }
      },
      "decision": {
        "reason": "Delete operation requires approval",
        "risk_level": "high"
      },
      "created_at": "2024-12-25T12:00:00Z",
      "expires_at": "2024-12-26T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Get Approval

Get details of a specific approval request.

HTTP
GET /v1/approvals/:id

Response

JSON
{
  "id": "apr_xyz789",
  "action_id": "act_abc123",
  "status": "pending",
  "action": {
    "tool": "http_proxy",
    "operation": "DELETE",
    "params": {
      "url": "https://api.company.com/customers/123"
    }
  },
  "decision": {
    "reason": "Delete operation requires approval",
    "risk_level": "high",
    "policy_id": "pol_default"
  },
  "assignees": [
    { "id": "user_1", "email": "admin@company.com" }
  ],
  "history": [],
  "created_at": "2024-12-25T12:00:00Z",
  "expires_at": "2024-12-26T12:00:00Z"
}

Approve Action

Approve a pending action.

HTTP
POST /v1/approvals/:id/approve

Request Body

JSON
{
  "comment": "Approved for production deployment"
}

Response

JSON
{
  "id": "apr_xyz789",
  "action_id": "act_abc123",
  "status": "approved",
  "approved_by": {
    "id": "user_1",
    "email": "admin@company.com"
  },
  "approved_at": "2024-12-25T12:05:00Z",
  "comment": "Approved for production deployment"
}

Deny Action

Deny a pending action.

HTTP
POST /v1/approvals/:id/deny

Request Body

JSON
{
  "reason": "Not authorized for this environment"
}

Response

JSON
{
  "id": "apr_xyz789",
  "action_id": "act_abc123",
  "status": "denied",
  "denied_by": {
    "id": "user_1",
    "email": "admin@company.com"
  },
  "denied_at": "2024-12-25T12:05:00Z",
  "reason": "Not authorized for this environment"
}

Reassign Approval

Reassign approval to different users.

HTTP
POST /v1/approvals/:id/reassign

Request Body

JSON
{
  "assignees": ["user_2", "user_3"],
  "comment": "Escalating to security team"
}

Approval Webhooks

Receive real-time notifications for approval events.

Webhook Events

  • approval.created - New approval request
  • approval.approved - Action approved
  • approval.denied - Action denied
  • approval.expired - Approval timed out
  • approval.escalated - Approval escalated

Webhook Payload

JSON
{
  "event": "approval.approved",
  "timestamp": "2024-12-25T12:05:00Z",
  "data": {
    "approval_id": "apr_xyz789",
    "action_id": "act_abc123",
    "approved_by": "admin@company.com",
    "comment": "Approved for production"
  }
}

SDK Examples

TypeScript
// List pending approvals
const pending = await client.listApprovals({
  status: 'pending',
  riskLevel: 'high',
});

// Approve an action
await client.approve(approvalId, {
  comment: 'Looks good, approved',
});

// Deny an action
await client.deny(approvalId, {
  reason: 'Security concern',
});

// Poll for approval (from agent side)
const result = await client.waitForApproval(actionId, {
  timeout: 300000,
  pollInterval: 5000,
});

Next Steps