Skip to main content

API Overview

FieldValue
Document IDASCEND-API-005
Version2026.04
Last UpdatedJune 2026
AuthorAscend Engineering Team
PublisherOW-KAI Technologies, Inc.
ClassificationEnterprise Client Documentation
ComplianceSOC 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.

Authentication Required

All API endpoints require authentication via Authorization: Bearer <api_key> header. Unauthenticated requests return 401 Unauthorized. See Rate Limits for per-endpoint quotas.

Base URL​

Production: https://pilot.owkai.app
Staging:    https://staging-pilot.owkai.app  [NOT YET AVAILABLE]

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​

HeaderRequiredDescription
X-API-KeyConditionalAPI key (if not using JWT)
AuthorizationConditionalJWT token (if not using API key)
Content-TypeYes (POST/PUT)application/json
AcceptRecommendedapplication/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​

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created
204No ContentSuccess, no body
400Bad RequestInvalid request
401UnauthorizedAuthentication failed
403ForbiddenInsufficient permissions
404Not FoundResource not found
409ConflictResource conflict
422UnprocessableValidation failed
429Too Many RequestsRate limited
500Server ErrorInternal error

Rate Limits​

Endpoint CategoryLimitScope
Action submission1000/minPer tenant
Authentication5/minPer IP
Analytics queries100/minPer API key
Admin operations50/minPer API key

Per-agent: 100/min. Sensitive endpoints (auth/admin): 30/min per user.

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  # [ROADMAP] — not yet available

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​

LanguagePackageStatus
Pythonascend-ai-sdkGA
Node.js@ascend-ai/sdkGA
RESTDirect APIGA

Python SDK​

from ascend import AscendClient

client = AscendClient(api_key="owkai_...")
result = client.evaluate_action(
    action_type="trade_execution",
    resource="trading_api",
    parameters={"symbol": "AAPL"}
)

Node.js SDK​

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

const client = new AscendClient({ apiKey: 'owkai_...' });
// Agent identity is bound at the constructor; evaluateAction takes actionType + resource.
const result = await client.evaluateAction({
    actionType: 'trade_execution',
    resource: 'trading_api',
    parameters: { symbol: 'AAPL' }
});

API Endpoints​

Core Endpoints​

EndpointMethodDescription
/api/v1/actions/submitPOSTSubmit action
/api/v1/actions/{id}GETGet action
/api/governance/pending-actionsGETList pending
/api/registry/agentsGETList agents
/api/registry/agentsPOSTRegister agent

Governance Endpoints​

EndpointMethodDescription
/api/smart-rulesGET/POSTManage rules
/api/governance/policiesGET/POSTManage policies
/api/governance/workflows/{id}/approvePOSTApprove action

Analytics Endpoints​

EndpointMethodDescription
/api/analytics/realtime/metricsGETReal-time metrics
/api/analytics/executive/dashboardGETDashboard data
/api/analytics/trendsGETTrend analysis

Next Steps​

Document Version: 2026.06 | Last Updated: June 2026