Actions API

Field	Value
Document ID	ASCEND-API-001
Version	2026.04
Last Updated	April 2026
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 10 minutes | Skill Level: Intermediate

Overview

The Actions API is the core of ASCEND governance. Use it to submit actions for evaluation, check action status, and manage approvals.

note

The Actions API evaluates each submission against all active policies and smart rules in real time. Action submissions are rate-limited to 100 requests per minute per agent by default.

Base URL

https://pilot.owkai.app/api/v1/actions

Submit Action

Submit an action for governance evaluation.

Request

POST /api/v1/actions/submit
Content-Type: application/json
X-API-Key: owkai_...

{
  "agent_id": "trading-bot-001",
  "action_type": "trade_execution",
  "description": "Execute stock trade for portfolio rebalancing",
  "parameters": {
    "symbol": "AAPL",
    "quantity": 100,
    "side": "buy",
    "order_type": "market"
  },
  "metadata": {
    "portfolio_id": "port_123",
    "strategy": "rebalance"
  }
}

Parameters

Field	Type	Required	Description
agent_id	string	Yes	Registered agent identifier
action_type	string	Yes	Type of action being performed
description	string	No	Human-readable description
parameters	object	No	Action-specific parameters
metadata	object	No	Additional context
require_approval	boolean	No	Force approval regardless of risk
callback_url	string	No	Webhook for async notification
resource_type	string	No	Triggers admin-defined classification lookup. When provided, the admin-defined sensitivity tier and risk modifier override any agent-submitted data_sensitivity value. See Resource Classification for details.
data_sensitivity	string	No, default "none"	Direct sensitivity declaration. Valid values: none, low_sensitivity, medium_sensitivity, high_sensitivity. Overridden when resource_type resolves to an admin-defined classification.

Resource Classification Example

{
  "agent_id": "agent-001",
  "action_type": "database_query",
  "description": "Query customer records",
  "tool_name": "postgresql",
  "resource_type": "database",
  "data_sensitivity": "high_sensitivity"
}

Resource Classification Override: When resource_type is provided and matches an admin-defined classification, the admin-defined sensitivity tier unconditionally overrides the data_sensitivity value. If the resource_type is not found in the classification table, fail-secure defaults apply: CRITICAL tier with a 1.5x risk score modifier, regardless of the submitted data_sensitivity. See Resource Classification Configuration for full details.

Response: Approved

{
  "status": "success",
  "data": {
    "action_id": "act_abc123",
    "decision": "approved",
    "risk_assessment": {
      "score": 35,
      "level": "medium",
      "factors": [
        {"name": "financial_impact", "score": 20},
        {"name": "operation_type", "score": 10},
        {"name": "agent_trust", "score": 5}
      ]
    },
    "policy_result": {
      "matched_rule": "auto-approve-low-risk",
      "action": "AUTO_APPROVE"
    },
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

Response: Pending Approval

HTTP/1.1 202 Accepted

{
  "status": "success",
  "data": {
    "action_id": "act_xyz789",
    "decision": "pending_approval",
    "risk_assessment": {
      "score": 75,
      "level": "high",
      "factors": [
        {"name": "financial_impact", "score": 40},
        {"name": "operation_type", "score": 20},
        {"name": "data_sensitivity", "score": 15}
      ]
    },
    "approval_required": {
      "level": 3,
      "role": "manager",
      "timeout_minutes": 60
    },
    "poll_url": "/api/v1/actions/act_xyz789/status",
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

Response: Denied

{
  "status": "success",
  "data": {
    "action_id": "act_denied123",
    "decision": "denied",
    "risk_assessment": {
      "score": 95,
      "level": "critical"
    },
    "denial_reason": "Action violates policy 'no-large-trades-after-hours'",
    "policy_result": {
      "matched_rule": "no-large-trades-after-hours",
      "action": "DENY"
    },
    "timestamp": "2025-12-15T22:30:00Z"
  }
}

Get Action Status

Check the status of a submitted action.

Request

GET /api/v1/actions/{action_id}
X-API-Key: owkai_...

Response

{
  "status": "success",
  "data": {
    "action_id": "act_xyz789",
    "agent_id": "trading-bot-001",
    "action_type": "trade_execution",
    "description": "Execute stock trade",
    "parameters": {
      "symbol": "AAPL",
      "quantity": 100
    },
    "current_status": "pending_approval",
    "risk_assessment": {
      "score": 75,
      "level": "high"
    },
    "approval_status": {
      "required_level": 3,
      "current_approvals": [],
      "timeout_at": "2025-12-15T11:30:00Z"
    },
    "created_at": "2025-12-15T10:30:00Z",
    "updated_at": "2025-12-15T10:30:00Z"
  }
}

List Actions

Query actions with filtering and pagination.

Request

GET /api/v1/actions?status=pending_approval&agent_id=trading-bot-001&limit=20
X-API-Key: owkai_...

Query Parameters

Parameter	Type	Description
status	string	Filter by status (approved, denied, pending_approval)
agent_id	string	Filter by agent
action_type	string	Filter by action type
risk_level	string	Filter by risk level (low, medium, high, critical)
from_date	ISO8601	Start date filter
to_date	ISO8601	End date filter
limit	integer	Results per page (max 100)
offset	integer	Pagination offset

Response

{
  "status": "success",
  "data": {
    "actions": [
      {
        "action_id": "act_xyz789",
        "agent_id": "trading-bot-001",
        "action_type": "trade_execution",
        "status": "pending_approval",
        "risk_score": 75,
        "created_at": "2025-12-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

Approve Action

Approve a pending action (requires appropriate role).

Request

POST /api/v1/actions/{action_id}/approve
Authorization: Bearer <jwt_token>
X-CSRF-Token: <csrf_token>
Content-Type: application/json

{
  "comment": "Approved after reviewing trade parameters",
  "conditions": {
    "max_slippage": "0.5%"
  }
}

Response

{
  "status": "success",
  "data": {
    "action_id": "act_xyz789",
    "decision": "approved",
    "approved_by": "manager@company.com",
    "approved_at": "2025-12-15T10:45:00Z",
    "comment": "Approved after reviewing trade parameters"
  }
}

Reject Action

Reject a pending action.

Request

POST /api/v1/actions/{action_id}/reject
Authorization: Bearer <jwt_token>
X-CSRF-Token: <csrf_token>
Content-Type: application/json

{
  "reason": "Trade amount exceeds daily limit",
  "recommendation": "Split into smaller trades"
}

Response

{
  "status": "success",
  "data": {
    "action_id": "act_xyz789",
    "decision": "denied",
    "rejected_by": "manager@company.com",
    "rejected_at": "2025-12-15T10:45:00Z",
    "reason": "Trade amount exceeds daily limit"
  }
}

Cancel Action

Cancel a pending action.

Request

POST /api/v1/actions/{action_id}/cancel
X-API-Key: owkai_...

Response

{
  "status": "success",
  "data": {
    "action_id": "act_xyz789",
    "decision": "cancelled",
    "cancelled_at": "2025-12-15T10:50:00Z"
  }
}

Action Types Reference

Common Action Types

Type	Description	Typical Risk
data_read	Read data from source	Low
data_write	Write/update data	Medium
data_delete	Delete data	High
data_export	Export data externally	High
api_call	External API call	Medium
file_read	Read file system	Low
file_write	Write to file system	Medium
trade_execution	Financial trade	High
payment_initiate	Payment processing	Critical
user_modify	Modify user data	High
config_change	System configuration	Critical

Custom Action Types

Register custom action types for your use case:

curl -X POST "https://pilot.owkai.app/api/action-types" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "name": "inventory_update",
    "description": "Update inventory levels",
    "default_risk_score": 40,
    "required_parameters": ["sku", "quantity"],
    "category": "operations"
  }'

SDK Examples

Python

from ascend import AscendClient

client = AscendClient(api_key="owkai_...")

# Submit action
result = client.submit_action(
    agent_id="my-agent",
    action_type="data_read",
    parameters={"query": "SELECT * FROM customers"}
)

if result.decision == "approved":
    execute_query()
elif result.decision == "pending_approval":
    # Wait for approval
    final = client.wait_for_approval(result.action_id, timeout=60)
    if final.decision == "approved":
        execute_query()

Node.js

const { AscendClient } = require('@ascend-ai/sdk');

const client = new AscendClient({ apiKey: 'owkai_...' });

const result = await client.submitAction({
  agentId: 'my-agent',
  actionType: 'data_read',
  parameters: { query: 'SELECT * FROM customers' }
});

if (result.decision === 'approved') {
  await executeQuery();
} else if (result.decision === 'pending_approval') {
  const final = await client.waitForApproval(result.actionId, { timeout: 60000 });
  if (final.decision === 'approved') {
    await executeQuery();
  }
}

Next Steps

• Agents API - Manage agents
• Rate Limits - API limits
• Errors - Error handling

---

Document Version: 2026.04 | Last Updated: April 2026