Submit Action

Submit an agent action through the complete 7-step governance pipeline for risk assessment, policy evaluation, and authorization.

Endpoint

POST /api/v1/actions/submit

Authentication

This endpoint supports both authentication methods:

API Key: X-API-Key header (recommended for SDKs)
JWT Token: Authorization: Bearer <token> header

Request

Headers

Header	Required	Description
`X-API-Key`	Yes*	Your API key
`Authorization`	Yes*	Bearer token (alternative to X-API-Key)
`Content-Type`	Yes	Must be `application/json`

*One of X-API-Key or Authorization is required.

Body

{
  "agent_id": "my-production-agent",
  "action_type": "database_query",
  "description": "Query user records from production database",
  "tool_name": "postgresql",
  "target_system": "production-db-01",
  "nist_control": "AC-3",
  "mitre_tactic": "TA0009"
}

Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Unique identifier for the AI agent
`action_type`	string	Yes	Type of action (e.g., `database_query`, `file_write`, `api_call`)
`description`	string	Yes	Human-readable description of the action
`tool_name`	string	Yes	Name of the tool/service being used
`target_system`	string	No	Target system identifier
`target_resource`	string	No	Specific resource being accessed
`nist_control`	string	No	NIST 800-53 control ID (auto-detected if omitted)
`mitre_tactic`	string	No	MITRE ATT&CK tactic ID (auto-detected if omitted)
`action_details`	object	No	Additional context for code/prompt analysis

Action Details Object

For enhanced security analysis, include action details:

{
  "agent_id": "code-assistant",
  "action_type": "code_execution",
  "description": "Execute SQL query",
  "tool_name": "database",
  "action_details": {
    "query": "SELECT * FROM users WHERE id = $1",
    "code": "def process_data(x): return x * 2",
    "command": "ls -la /var/log"
  }
}

Response

Success (200 OK)

{
  "id": 12345,
  "action_id": 12345,
  "status": "approved",
  "risk_score": 35.0,
  "risk_level": "low",
  "cvss_score": 3.5,
  "cvss_severity": "LOW",
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
  "requires_approval": false,
  "alert_triggered": false,
  "alert_id": null,
  "workflow_id": null,
  "policy_decision": "allow",
  "matched_policies": 2,
  "matched_smart_rules": 0,
  "correlation_id": "action_20260120_143052_abc12345",
  "processing_time_ms": 45,
  "action_type": "database_query",
  "nist_control": "AC-3",
  "nist_description": "Access Enforcement",
  "mitre_tactic": "TA0009",
  "mitre_technique": "T1005",
  "thresholds": {
    "auto_approve_below": 30,
    "max_risk_threshold": 80,
    "agent_type": "supervised",
    "is_registered": true
  },
  "code_analysis": null,
  "prompt_security": null,
  "message": "Action processed through complete governance pipeline - Status: approved"
}

Pending Approval (200 OK)

When the action requires human approval:

{
  "id": 12346,
  "action_id": 12346,
  "status": "pending_approval",
  "risk_score": 75.0,
  "risk_level": "high",
  "cvss_score": 7.5,
  "cvss_severity": "HIGH",
  "requires_approval": true,
  "alert_triggered": true,
  "alert_id": 789,
  "workflow_id": 42,
  "policy_decision": "require_approval",
  "correlation_id": "action_20260120_143055_def67890",
  "message": "Action processed through complete governance pipeline - Status: pending_approval"
}

Response Fields

Field	Type	Description
`id`	integer	Unique action identifier
`action_id`	integer	Alias for `id` (SDK compatibility)
`status`	string	`approved`, `pending_approval`, or `denied`
`risk_score`	float	Calculated risk score (0-100)
`risk_level`	string	`low`, `medium`, `high`, or `critical`
`cvss_score`	float	CVSS v3.1 base score (0-10)
`cvss_severity`	string	CVSS severity rating
`cvss_vector`	string	CVSS v3.1 vector string
`requires_approval`	boolean	Whether human approval is required
`alert_triggered`	boolean	Whether a security alert was created
`alert_id`	integer	ID of created alert (if any)
`workflow_id`	integer	ID of assigned approval workflow (if any)
`policy_decision`	string	Policy engine decision: `allow`, `deny`, `require_approval`
`matched_policies`	integer	Number of policies that matched
`matched_smart_rules`	integer	Number of smart rules that matched
`correlation_id`	string	Unique ID for request tracing
`processing_time_ms`	integer	Total processing time in milliseconds
`nist_control`	string	Mapped NIST 800-53 control
`mitre_tactic`	string	Mapped MITRE ATT&CK tactic
`thresholds`	object	Agent-specific threshold configuration
`code_analysis`	object	Code security analysis results (if applicable)
`prompt_security`	object	Prompt injection analysis results (if applicable)

Errors

Code	Description
400	Bad request - invalid JSON or parameters
401	Unauthorized - missing or invalid credentials
402	Payment required - spend limit exceeded
403	Forbidden - action denied by policy
422	Unprocessable entity - missing required fields
429	Too many requests - rate limit exceeded
500	Internal server error

Validation Error (422):

{
  "detail": "Missing required fields: agent_id, action_type",
  "error_code": "MISSING_FIELD",
  "status": 422
}

Rate Limit Error (429):

{
  "detail": "Rate limit exceeded: 100 requests per minute",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "status": 429,
  "retry_after": 45
}

Spend Limit Error (402):

{
  "detail": "Spend limit exceeded or kill-switch active",
  "error_code": "SPEND_LIMIT_EXCEEDED",
  "status": 402
}

Governance Pipeline

The submit endpoint processes actions through a complete 7-step governance pipeline:

Risk Assessment - Security enrichment with NIST/MITRE mapping
CVSS Calculation - Quantitative risk scoring using CVSS v3.1
Policy Evaluation - Check against organization governance policies
Smart Rules Check - Evaluate custom pattern-based rules
Alert Generation - Create alerts for high-risk actions (risk >= 70)
Workflow Routing - Assign to approval workflow if required
Audit Logging - Immutable compliance trail

Risk Thresholds

Actions are evaluated against configurable thresholds:

Risk Score	Risk Level	Default Behavior
0-29	Low	Auto-approved
30-69	Medium	Policy-dependent
70-84	High	Requires approval, alert generated
85-100	Critical	Requires approval, alert generated

Registered agents can have custom thresholds configured.

Examples

cURL

curl -X POST https://pilot.owkai.app/api/v1/actions/submit \
  -H "X-API-Key: owkai_admin_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-production-agent",
    "action_type": "database_query",
    "description": "Query user records from production database",
    "tool_name": "postgresql",
    "target_system": "production-db-01"
  }'

Python

from ascend import AscendClient

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

result = client.actions.submit(
    agent_id="my-production-agent",
    action_type="database_query",
    description="Query user records from production database",
    tool_name="postgresql",
    target_system="production-db-01"
)

if result.status == "approved":
    print(f"Action approved! ID: {result.id}")
    # Proceed with the action
elif result.status == "pending_approval":
    print(f"Action requires approval. ID: {result.id}")
    # Wait for approval or notify user
elif result.status == "denied":
    print(f"Action denied by policy")
    # Handle denial

Node.js

import { AscendClient } from '@anthropic/ascend-sdk';

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

const result = await client.actions.submit({
  agentId: 'my-production-agent',
  actionType: 'database_query',
  description: 'Query user records from production database',
  toolName: 'postgresql',
  targetSystem: 'production-db-01'
});

if (result.status === 'approved') {
  console.log(`Action approved! ID: ${result.id}`);
} else if (result.status === 'pending_approval') {
  console.log(`Action requires approval. ID: ${result.id}`);
} else if (result.status === 'denied') {
  console.log('Action denied by policy');
}

Python (requests)

import requests

response = requests.post(
    "https://pilot.owkai.app/api/v1/actions/submit",
    headers={
        "X-API-Key": "owkai_admin_...",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "my-production-agent",
        "action_type": "database_query",
        "description": "Query user records from production database",
        "tool_name": "postgresql",
        "target_system": "production-db-01"
    }
)

result = response.json()
print(f"Status: {result['status']}")
print(f"Risk Score: {result['risk_score']}")
print(f"Processing Time: {result['processing_time_ms']}ms")

Get Action Status - Poll for approval decision
Approve Action - Approve a pending action

Endpoint​

Authentication​

Request​

Headers​

Body​

Parameters​

Action Details Object​

Response​

Success (200 OK)​

Pending Approval (200 OK)​

Response Fields​

Errors​

Governance Pipeline​

Risk Thresholds​

Examples​

cURL​

Python​

Node.js​

Python (requests)​

Related Endpoints​