API Overview

Field	Value
Document ID	ASCEND-API-005
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: 6 minutes | Skill Level: Intermediate

Overview

The ASCEND API is a RESTful API that provides programmatic access to all governance features. Use the API to submit actions, manage agents, configure policies, and integrate with your systems.

Base URL

Production: https://pilot.owkai.app
Staging:    https://staging-pilot.owkai.app

Authentication

API Key Authentication

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

JWT Authentication (Dashboard)

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

Dual Authentication (Both)

Some endpoints accept either API key or JWT:

# Using API key
curl -H "X-API-Key: owkai_..."

# Or using JWT
curl -H "Authorization: Bearer ..."

Request Format

Headers

Header	Required	Description
X-API-Key	Conditional	API key (if not using JWT)
Authorization	Conditional	JWT token (if not using API key)
Content-Type	Yes (POST/PUT)	application/json
Accept	Recommended	application/json

Request Body

{
  "agent_id": "trading-bot-001",
  "action_type": "trade_execution",
  "description": "Execute buy order",
  "parameters": {
    "symbol": "AAPL",
    "quantity": 100
  }
}

Response Format

Success Response

{
  "status": "success",
  "data": {
    "action_id": "act_abc123",
    "risk_score": 65,
    "decision": "pending_approval"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

Error Response

{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: agent_id",
    "details": {
      "field": "agent_id",
      "requirement": "required"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created
204	No Content	Success, no body
400	Bad Request	Invalid request
401	Unauthorized	Authentication failed
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict
422	Unprocessable	Validation failed
429	Too Many Requests	Rate limited
500	Server Error	Internal error

Rate Limits

Endpoint Category	Limit	Window
Action submission	1000/min	Per API key
Authentication	5/min	Per IP
Analytics queries	100/min	Per API key
Admin operations	50/min	Per API key

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1702656060

Handling Rate Limits

import time

def api_call_with_retry(func):
    response = func()
    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        return func()
    return response

Pagination

Request

curl "https://pilot.owkai.app/api/v1/actions?limit=50&offset=100" \
  -H "X-API-Key: owkai_..."

Response

{
  "data": [...],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Filtering & Sorting

Query Parameters

# Filter by status
curl "https://pilot.owkai.app/api/v1/actions?status=pending_approval"

# Filter by risk level
curl "https://pilot.owkai.app/api/v1/actions?risk_level=high"

# Sort by creation date
curl "https://pilot.owkai.app/api/v1/actions?sort=created_at&order=desc"

# Date range
curl "https://pilot.owkai.app/api/v1/actions?start_date=2025-12-01&end_date=2025-12-15"

API Versioning

Version Header

curl "https://pilot.owkai.app/api/v1/actions" \
  -H "X-API-Version: 2025-12-01"

URL Versioning

/api/v1/actions  # Current stable
/api/v2/actions  # Beta features

Idempotency

For POST requests, use idempotency keys to prevent duplicate operations:

curl -X POST "https://pilot.owkai.app/api/v1/actions/submit" \
  -H "X-API-Key: owkai_..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"agent_id": "...", "action_type": "..."}'

Webhooks

Subscribe to events for real-time notifications:

curl -X POST "https://pilot.owkai.app/api/webhooks" \
  -H "Authorization: Bearer ..." \
  -d '{
    "target_url": "https://your-app.com/webhooks",
    "event_types": ["action.submitted", "action.approved"]
  }'

SDK Support

Language	Package	Status
Python	ascend-sdk	GA
Node.js	@ascend/sdk	GA
REST	Direct API	GA

Python SDK

from ascend import AscendClient

client = AscendClient(api_key="owkai_...")
result = client.submit_action(
    agent_id="trading-bot-001",
    action_type="trade_execution",
    parameters={"symbol": "AAPL"}
)

Node.js SDK

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

const client = new AscendClient({ apiKey: 'owkai_...' });
const result = await client.submitAction({
    agentId: 'trading-bot-001',
    actionType: 'trade_execution',
    parameters: { symbol: 'AAPL' }
});

API Endpoints

Core Endpoints

Endpoint	Method	Description
/api/v1/actions/submit	POST	Submit action
/api/v1/actions/{id}	GET	Get action
/api/governance/pending-actions	GET	List pending
/api/registry/agents	GET	List agents
/api/registry/agents	POST	Register agent

Governance Endpoints

Endpoint	Method	Description
/api/smart-rules	GET/POST	Manage rules
/api/governance/policies	GET/POST	Manage policies
/api/governance/workflows/{id}/approve	POST	Approve action

Analytics Endpoints

Endpoint	Method	Description
/api/analytics/realtime/metrics	GET	Real-time metrics
/api/analytics/executive/dashboard	GET	Dashboard data
/api/analytics/trends	GET	Trend analysis

Next Steps

• Actions API - Action endpoints
• Agents API - Agent management
• Errors - Error codes

---

Document Version: 1.0.0 | Last Updated: December 2025