DocumentationAgent Action Firewall
GitHub

Actions API

Submit, retrieve, and manage actions through the firewall.

Submit Action

Submit a new action for policy evaluation.

HTTP
POST /v1/actions

Request Body

JSON
{
  "tool": "http_proxy",
  "operation": "POST",
  "params": {
    "url": "https://api.example.com/data",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "key": "value"
    }
  },
  "idempotency_key": "optional-unique-key-123",
  "metadata": {
    "customer_id": "cust_123",
    "request_id": "req_456"
  }
}

Parameters

FieldTypeRequiredDescription
toolstringYesTool identifier (e.g., http_proxy, database)
operationstringYesOperation type (e.g., GET, POST, query)
paramsobjectYesOperation-specific parameters
idempotency_keystringNoUnique key for idempotent requests
metadataobjectNoCustom metadata for logging

Response

JSON
{
  "id": "act_abc123xyz",
  "status": "allowed",
  "tool": "http_proxy",
  "operation": "POST",
  "decision": {
    "decision": "allow",
    "reason": "Action matches allowed pattern",
    "risk_level": "low",
    "policy_id": "pol_default"
  },
  "created_at": "2024-12-25T12:00:00Z"
}

Status Values

  • allowed - Action approved, proceed with execution
  • denied - Action blocked by policy
  • pending_approval - Waiting for human approval

Get Action

Retrieve the current status of an action.

HTTP
GET /v1/actions/:id

Response

JSON
{
  "id": "act_abc123xyz",
  "status": "succeeded",
  "tool": "http_proxy",
  "operation": "POST",
  "params": {
    "url": "https://api.example.com/data"
  },
  "decision": {
    "decision": "allow",
    "reason": "Action matches allowed pattern",
    "risk_level": "low"
  },
  "execution": {
    "id": "exec_xyz789",
    "status": "succeeded",
    "attempts": 1,
    "started_at": "2024-12-25T12:00:01Z",
    "completed_at": "2024-12-25T12:00:02Z",
    "result": {
      "statusCode": 200,
      "body": { "success": true }
    }
  },
  "approval": null,
  "created_at": "2024-12-25T12:00:00Z",
  "updated_at": "2024-12-25T12:00:02Z"
}

List Actions

List actions with filtering and pagination.

HTTP
GET /v1/actions?status=pending_approval&limit=20&offset=0

Query Parameters

ParameterTypeDescription
statusstringFilter by status
toolstringFilter by tool
agent_idstringFilter by agent
sincedatetimeActions created after this time
untildatetimeActions created before this time
limitintegerMax results (default: 20, max: 100)
offsetintegerPagination offset

Response

JSON
{
  "data": [
    {
      "id": "act_abc123",
      "status": "pending_approval",
      "tool": "http_proxy",
      "operation": "DELETE",
      "created_at": "2024-12-25T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Cancel Action

Cancel a pending action.

HTTP
POST /v1/actions/:id/cancel

Request Body

JSON
{
  "reason": "No longer needed"
}

SDK Examples

TypeScript
// Submit action
const action = await client.submitAction({
  tool: 'http_proxy',
  operation: 'POST',
  params: { url: 'https://api.example.com' },
});

// Get action status
const status = await client.getAction(action.id);

// List pending actions
const pending = await client.listActions({
  status: 'pending_approval',
  limit: 10,
});

// Wait for approval
const approved = await client.waitForApproval(action.id, {
  timeout: 300000,
  pollInterval: 5000,
});

Next Steps