Actions API

Field	Value
Document ID	ASCEND-API-001
Version	1.0.0
Last Updated	December 19, 2025
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.

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

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('@owkai/ascend-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: 1.0.0 | Last Updated: December 2025