List Policies

Retrieve governance policies configured for your organization. Policies define how agent actions and MCP server operations are evaluated.

Endpoint

GET /api/mcp/policies

Authentication

JWT Token required - Authorization: Bearer <token> header

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Query Parameters

Parameter	Type	Default	Description
active_only	boolean	true	Return only active policies

Response

Success (200 OK)

{
  "total": 3,
  "policies": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "policy_name": "Block Production Database Writes",
      "policy_description": "Block all write operations to production databases",
      "action": "DENY",
      "risk_threshold": 50,
      "required_approval_level": 3,
      "is_active": true,
      "priority": 100,
      "execution_count": 1542,
      "created_by": "admin@company.com",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "policy_name": "PII Access Approval Required",
      "policy_description": "Require approval for any PII data access",
      "action": "EVALUATE",
      "risk_threshold": 40,
      "required_approval_level": 2,
      "is_active": true,
      "priority": 90,
      "execution_count": 892,
      "created_by": "security@company.com",
      "created_at": "2026-01-10T14:30:00Z"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "policy_name": "Auto-Approve Read Operations",
      "policy_description": "Automatically approve low-risk read operations",
      "action": "ALLOW",
      "risk_threshold": 30,
      "required_approval_level": 1,
      "is_active": true,
      "priority": 50,
      "execution_count": 15234,
      "created_by": "admin@company.com",
      "created_at": "2026-01-05T09:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
total	integer	Total number of policies returned
policies	array	List of policy objects
policies[].id	string	Unique policy identifier (UUID)
policies[].policy_name	string	Policy name
policies[].policy_description	string	Policy description
policies[].action	string	Policy action: ALLOW, DENY, EVALUATE
policies[].risk_threshold	integer	Risk score threshold (0-100)
policies[].required_approval_level	integer	Required approval level (1-5)
policies[].is_active	boolean	Whether policy is active
policies[].priority	integer	Policy priority (higher = evaluated first)
policies[].execution_count	integer	Number of times policy has been evaluated
policies[].created_by	string	Email of policy creator
policies[].created_at	string	ISO 8601 creation timestamp

Errors

Code	Description
401	Unauthorized - missing or invalid JWT token
500	Internal server error

Examples

cURL

# List all active policies
curl -X GET https://pilot.owkai.app/api/mcp/policies \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."

# List all policies including inactive
curl -X GET "https://pilot.owkai.app/api/mcp/policies?active_only=false" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."

Python

from ascend import AscendClient

client = AscendClient(access_token="eyJhbGciOiJSUzI1NiI...")

# List all active policies
policies = client.policies.list()
print(f"Total policies: {policies.total}")

for policy in policies.policies:
    print(f"- {policy.policy_name}")
    print(f"  Action: {policy.action}")
    print(f"  Risk Threshold: {policy.risk_threshold}")
    print(f"  Executions: {policy.execution_count}")

# List all policies including inactive
all_policies = client.policies.list(active_only=False)

Node.js

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

const client = new AscendClient({ accessToken: 'eyJhbGciOiJSUzI1NiI...' });

// List all active policies
const policies = await client.policies.list();
console.log(`Total policies: ${policies.total}`);

policies.policies.forEach(policy => {
  console.log(`- ${policy.policyName}: ${policy.action}`);
});

Python (requests)

import requests

response = requests.get(
    "https://pilot.owkai.app/api/mcp/policies",
    headers={"Authorization": "Bearer eyJhbGciOiJSUzI1NiI..."},
    params={"active_only": True}
)

result = response.json()
print(f"Found {result['total']} policies")

for policy in result["policies"]:
    status = "Active" if policy["is_active"] else "Inactive"
    print(f"[{status}] {policy['policy_name']}: {policy['action']}")

Get Single Policy

To get detailed information about a specific policy:

GET /api/mcp/policies/{policy_id}

Example:

curl -X GET https://pilot.owkai.app/api/mcp/policies/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "policy_name": "Block Production Database Writes",
  "policy_description": "Block all write operations to production databases",
  "server_patterns": ["*-production-*", "prod-*"],
  "namespace_patterns": ["database"],
  "verb_patterns": ["write_*", "delete_*", "update_*"],
  "resource_patterns": ["production-db/*", "prod-*"],
  "risk_threshold": 50,
  "action": "DENY",
  "required_approval_level": 3,
  "compliance_framework": "SOC2",
  "is_active": true,
  "priority": 100,
  "execution_count": 1542,
  "last_executed_at": "2026-01-20T14:30:00Z",
  "created_by": "admin@company.com",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-18T16:00:00Z"
}

List Agent-Specific Policies

To list policies for a specific agent:

GET /api/registry/agents/{agent_id}/policies

Example:

curl -X GET https://pilot.owkai.app/api/registry/agents/my-production-agent/policies \
  -H "X-API-Key: owkai_admin_..."

Response:

{
  "success": true,
  "agent_id": "my-production-agent",
  "policies": [
    {
      "id": 123,
      "policy_name": "Block PII Access",
      "policy_description": "Block access to PII data",
      "policy_action": "block",
      "priority": 100,
      "is_active": true,
      "conditions": {"resource_contains": "pii"},
      "action_params": {},
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Policy Statistics

Get policy execution statistics from the dashboard:

GET /api/mcp/analytics/dashboard

Response includes:

{
  "time_range_hours": 24,
  "summary": {
    "total_actions": 1542,
    "auto_approved": 892,
    "denied": 123,
    "pending_approval": 45
  },
  "policy_stats": {
    "most_triggered": [
      {"policy_name": "Auto-Approve Read Operations", "count": 892},
      {"policy_name": "PII Access Approval Required", "count": 234}
    ],
    "most_denied": [
      {"policy_name": "Block Production Database Writes", "count": 123}
    ]
  }
}

Update Policy

To update an existing policy:

PUT /api/mcp/policies/{policy_id}

Request Body:

{
  "policy_description": "Updated description",
  "risk_threshold": 60,
  "is_active": false
}

Delete Policy

To delete a policy:

DELETE /api/mcp/policies/{policy_id}

Note: Deleting a policy creates an audit log entry and cannot be undone.

Related Endpoints

• Create Policy - Create a new policy