REST API Reference

Field	Value
Document ID	ASCEND-SDK-012
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: 15 minutes | Skill Level: Intermediate

Overview

The ASCEND REST API allows direct HTTP integration from any programming language or platform. All endpoints use JSON request/response bodies and require authentication.

Base URL

https://pilot.owkai.app

Authentication

All requests require an API key via one of these methods:

Bearer Token (Recommended)

curl -H "Authorization: Bearer owkai_your_key_here" \
     https://pilot.owkai.app/api/v1/actions/submit

X-API-Key Header

curl -H "X-API-Key: owkai_your_key_here" \
     https://pilot.owkai.app/api/v1/actions/submit

Both Headers (Enterprise)

For banking-level security, include both:

curl -H "Authorization: Bearer owkai_your_key_here" \
     -H "X-API-Key: owkai_your_key_here" \
     https://pilot.owkai.app/api/v1/actions/submit

Common Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api_key>`
`Content-Type`	Yes	`application/json`
`X-API-Key`	Optional	Alternate authentication
`X-Correlation-ID`	Optional	Request tracing ID
`X-Request-Timestamp`	Optional	ISO 8601 timestamp

Action Endpoints

Submit Action

Submit an agent action for governance evaluation.

Endpoint: POST /api/v1/actions/submit

Request Body:

{
    "agent_id": "my-agent-001",
    "agent_name": "My AI Agent",
    "action_type": "database_read",
    "description": "Read customer data for report",
    "tool_name": "postgresql",
    "resource_id": "customers_table",
    "action_details": {
        "table": "customers",
        "operation": "SELECT",
        "columns": ["id", "name", "email"]
    },
    "context": {
        "session_id": "sess_abc123",
        "environment": "production"
    },
    "risk_indicators": {
        "data_classification": "pii"
    }
}

Required Fields:

Field	Type	Description
`agent_id`	string	Unique agent identifier
`agent_name`	string	Human-readable agent name
`action_type`	string	Action category
`description`	string	What the action does
`tool_name`	string	Tool/service being used

Optional Fields:

Field	Type	Description
`resource_id`	string	Target resource identifier
`action_details`	object	Action-specific parameters
`context`	object	Execution context
`risk_indicators`	object	Pre-computed risk signals

Response (200 OK):

{
    "id": 12345,
    "action_id": "act_abc123xyz",
    "status": "approved",
    "risk_score": 3.5,
    "risk_level": "low",
    "summary": "Action approved - low risk database read",
    "created_at": "2025-12-16T10:30:00Z",
    "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
    "nist_controls": ["AC-3", "AU-12"],
    "mitre_techniques": []
}

Response Fields:

Field	Type	Description
`id`	integer	Numeric action ID
`action_id`	string	String action ID
`status`	string	`approved`, `denied`, `pending`
`risk_score`	float	Risk score (0-100)
`risk_level`	string	`low`, `medium`, `high`, `critical`
`summary`	string	Decision explanation
`denial_reason`	string	Reason if denied
`pending_approvers`	array	Approvers if pending

Example:

curl -X POST https://pilot.owkai.app/api/v1/actions/submit \
  -H "Authorization: Bearer owkai_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "agent_name": "My Agent",
    "action_type": "database_read",
    "description": "Query customers",
    "tool_name": "postgresql"
  }'

Get Action Status

Check the status of a submitted action.

Endpoint: GET /api/v1/actions/{action_id}/status

Response (200 OK):

{
    "id": 12345,
    "status": "approved",
    "risk_score": 3.5,
    "risk_level": "low",
    "updated_at": "2025-12-16T10:30:00Z"
}

Example:

curl https://pilot.owkai.app/api/v1/actions/12345/status \
  -H "Authorization: Bearer owkai_your_key_here"

Get Action Details

Get full action details including audit trail.

Endpoint: GET /api/v1/actions/{action_id}

Response (200 OK):

{
    "id": 12345,
    "agent_id": "my-agent-001",
    "agent_name": "My AI Agent",
    "action_type": "database_read",
    "description": "Query customers",
    "status": "approved",
    "risk_score": 3.5,
    "risk_level": "low",
    "created_at": "2025-12-16T10:30:00Z",
    "audit_trail": [
        {
            "timestamp": "2025-12-16T10:30:00Z",
            "event": "submitted",
            "actor": "agent"
        },
        {
            "timestamp": "2025-12-16T10:30:01Z",
            "event": "approved",
            "actor": "auto"
        }
    ]
}

List Actions

List recent actions with optional filtering.

Endpoint: GET /api/v1/actions

Query Parameters:

Parameter	Type	Default	Description
`limit`	int	50	Max results (1-100)
`offset`	int	0	Pagination offset
`status`	string	-	Filter by status
`agent_id`	string	-	Filter by agent

Response (200 OK):

{
    "actions": [
        {
            "id": 12345,
            "agent_id": "my-agent",
            "action_type": "database_read",
            "status": "approved",
            "risk_level": "low",
            "created_at": "2025-12-16T10:30:00Z"
        }
    ],
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
}

Example:

curl "https://pilot.owkai.app/api/v1/actions?limit=10&status=pending" \
  -H "Authorization: Bearer owkai_your_key_here"

Agent Endpoints

Register Agent

Endpoint: POST /api/registry/agents

Request Body:

{
    "agent_id": "my-agent-001",
    "display_name": "My AI Agent",
    "agent_type": "supervised",
    "environment": "production",
    "capabilities": ["data_access", "file_operations"],
    "allowed_resources": ["production_db"],
    "metadata": {
        "version": "1.0.0",
        "team": "data-engineering"
    }
}

Response (201 Created):

{
    "agent_id": "my-agent-001",
    "status": "active",
    "trust_level": "standard",
    "created_at": "2025-12-16T10:30:00Z"
}

Get Agent Status

Endpoint: GET /api/registry/agents/{agent_id}

Response (200 OK):

{
    "agent_id": "my-agent-001",
    "display_name": "My AI Agent",
    "status": "active",
    "trust_level": "standard",
    "last_activity": "2025-12-16T10:30:00Z",
    "action_count": 150,
    "denial_count": 5
}

Approval Endpoints

Check Approval Status

Endpoint: GET /api/sdk/approval/{approval_id}

Response (200 OK):

{
    "approval_id": "apr_abc123",
    "status": "approved",
    "approved_by": "admin@company.com",
    "decided_at": "2025-12-16T10:35:00Z",
    "comments": "Approved for production deployment"
}

Approve Action (Admin)

Endpoint: POST /api/actions/{action_id}/approve

Request Body:

{
    "comments": "Approved after security review"
}

Response (200 OK):

{
    "status": "approved",
    "approved_by": "admin@company.com",
    "approved_at": "2025-12-16T10:35:00Z"
}

Health & Info

Health Check

Endpoint: GET /health

Response (200 OK):

{
    "status": "healthy",
    "timestamp": "2025-12-16T10:30:00Z"
}

Deployment Info

Endpoint: GET /api/deployment-info

Response (200 OK):

{
    "version": "2.5.0",
    "environment": "production",
    "region": "us-east-2",
    "features": ["smart_rules", "mcp_governance", "byok"]
}

Error Responses

Error Format

All errors return JSON with this structure:

{
    "detail": "Error message here",
    "error_code": "ERROR_CODE",
    "status_code": 400
}

HTTP Status Codes

Code	Meaning	Common Causes
200	Success	Request completed
201	Created	Resource created
400	Bad Request	Invalid JSON, missing fields
401	Unauthorized	Invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource
422	Unprocessable	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error

Error Codes

Code	Description
`INVALID_API_KEY`	API key is invalid or expired
`MISSING_REQUIRED_FIELD`	Required field not provided
`INVALID_ACTION_TYPE`	Unrecognized action type
`AGENT_NOT_FOUND`	Agent ID not registered
`RATE_LIMIT_EXCEEDED`	Too many requests
`POLICY_VIOLATION`	Action violates policy

Rate Limits

Tier	Requests/Minute	Requests/Hour
Free	60	1,000
Pro	600	10,000
Enterprise	6,000	Unlimited

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702725600
Retry-After: 30

Webhooks

Configure Webhook

Endpoint: POST /api/sdk/webhooks/configure

Request Body:

{
    "url": "https://your-app.com/webhooks/ascend",
    "events": ["action.approved", "action.denied", "policy.violation"],
    "secret": "whsec_your_secret_here"
}

Webhook Payload:

{
    "event": "action.approved",
    "timestamp": "2025-12-16T10:30:00Z",
    "data": {
        "action_id": "act_abc123",
        "agent_id": "my-agent-001",
        "risk_score": 3.5
    },
    "signature": "v1=abc123..."
}

Complete Example

import requests
import os

BASE_URL = "https://pilot.owkai.app"
API_KEY = os.environ["ASCEND_API_KEY"]

def submit_action(action_type, description, tool_name, **kwargs):
    """Submit an action for governance evaluation."""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "agent_id": "my-agent-001",
        "agent_name": "My AI Agent",
        "action_type": action_type,
        "description": description,
        "tool_name": tool_name,
        **kwargs
    }

    response = requests.post(
        f"{BASE_URL}/api/v1/actions/submit",
        headers=headers,
        json=payload,
        timeout=30
    )

    if response.status_code == 200:
        result = response.json()
        return result
    elif response.status_code == 401:
        raise Exception("Invalid API key")
    elif response.status_code == 422:
        raise Exception(f"Validation error: {response.json()}")
    else:
        raise Exception(f"API error: {response.status_code}")

# Usage
result = submit_action(
    action_type="database_read",
    description="Query customer data",
    tool_name="postgresql",
    action_details={"table": "customers"}
)

if result["status"] == "approved":
    print(f"Approved! Action ID: {result['id']}")
else:
    print(f"Status: {result['status']}")

Next Steps

Python SDK — Python SDK wrapper
Node.js SDK — Node.js SDK wrapper
Gateway Overview — API Gateway integration

Document Version: 1.0.0 | Last Updated: December 2025

Overview​

Base URL​

Authentication​

Bearer Token (Recommended)​

X-API-Key Header​

Both Headers (Enterprise)​

Common Headers​

Action Endpoints​

Submit Action​

Get Action Status​

Get Action Details​

List Actions​

Agent Endpoints​

Register Agent​

Get Agent Status​

Approval Endpoints​

Check Approval Status​

Approve Action (Admin)​

Health & Info​

Health Check​

Deployment Info​

Error Responses​

Error Format​

HTTP Status Codes​

Error Codes​

Rate Limits​

Webhooks​

Configure Webhook​

Complete Example​

Next Steps​

Overview

Base URL

Authentication

Bearer Token (Recommended)

X-API-Key Header

Both Headers (Enterprise)

Common Headers

Action Endpoints

Submit Action

Get Action Status

Get Action Details

List Actions

Agent Endpoints

Register Agent

Get Agent Status

Approval Endpoints

Check Approval Status

Approve Action (Admin)

Health & Info

Health Check

Deployment Info

Error Responses

Error Format

HTTP Status Codes

Error Codes

Rate Limits

Webhooks

Configure Webhook

Complete Example

Next Steps