Agents API

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

Overview

The Agents API allows you to register, manage, and monitor AI agents. All agents must be registered before they can submit actions.

Base URL

https://pilot.owkai.app/api/registry

Register Agent

Request

POST /api/registry/agents
X-API-Key: owkai_...
Content-Type: application/json

{
  "agent_id": "trading-bot-001",
  "agent_type": "trading",
  "name": "Trading Bot Primary",
  "description": "Automated stock trading agent for portfolio management",
  "capabilities": ["trade_execution", "market_analysis", "portfolio_rebalance"],
  "owner_email": "trading-team@company.com",
  "metadata": {
    "version": "2.1.0",
    "framework": "custom",
    "environment": "production"
  },
  "config": {
    "max_trade_amount": 100000,
    "allowed_symbols": ["AAPL", "GOOGL", "MSFT"],
    "trading_hours_only": true
  }
}

Parameters

Field	Type	Required	Description
`agent_id`	string	Yes	Unique identifier (lowercase, alphanumeric, hyphens)
`agent_type`	string	Yes	Category (trading, data-processor, assistant, etc.)
`name`	string	No	Human-readable name
`description`	string	No	Agent purpose description
`capabilities`	array	No	List of action types agent can perform
`owner_email`	string	No	Contact email for agent owner
`metadata`	object	No	Additional metadata
`config`	object	No	Agent-specific configuration

Response

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "registration_id": "reg_abc123",
    "status": "active",
    "trust_level": "standard",
    "api_key": "owkai_agent_xyz789...",
    "registered_at": "2025-12-15T10:00:00Z",
    "message": "Agent registered successfully"
  }
}

Get Agent

Retrieve agent details.

Request

GET /api/registry/agents/{agent_id}
X-API-Key: owkai_...

Response

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "agent_type": "trading",
    "name": "Trading Bot Primary",
    "status": "active",
    "trust_level": "elevated",
    "health": {
      "status": "healthy",
      "last_heartbeat": "2025-12-15T10:29:30Z",
      "uptime_percent": 99.9
    },
    "statistics": {
      "total_actions": 1250,
      "approved_actions": 1200,
      "denied_actions": 50,
      "avg_risk_score": 35,
      "last_action_at": "2025-12-15T10:25:00Z"
    },
    "registered_at": "2025-11-01T08:00:00Z"
  }
}

List Agents

List all registered agents with filtering.

Request

GET /api/registry/agents?status=active&agent_type=trading&limit=20
X-API-Key: owkai_...

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (active, inactive, suspended, killed)
`agent_type`	string	Filter by type
`trust_level`	string	Filter by trust level
`health_status`	string	Filter by health (healthy, warning, critical)
`limit`	integer	Results per page (max 100)
`offset`	integer	Pagination offset

Response

{
  "status": "success",
  "data": {
    "agents": [
      {
        "agent_id": "trading-bot-001",
        "agent_type": "trading",
        "name": "Trading Bot Primary",
        "status": "active",
        "trust_level": "elevated",
        "health_status": "healthy",
        "last_action_at": "2025-12-15T10:25:00Z"
      },
      {
        "agent_id": "data-processor-01",
        "agent_type": "data-processor",
        "name": "ETL Pipeline Agent",
        "status": "active",
        "trust_level": "standard",
        "health_status": "healthy",
        "last_action_at": "2025-12-15T10:28:00Z"
      }
    ],
    "pagination": {
      "total": 12,
      "limit": 20,
      "offset": 0,
      "has_more": false
    }
  }
}

Update Agent

Update agent configuration.

Request

PUT /api/registry/agents/{agent_id}
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "name": "Trading Bot Primary v2",
  "description": "Updated trading agent",
  "capabilities": ["trade_execution", "market_analysis", "portfolio_rebalance", "risk_assessment"],
  "config": {
    "max_trade_amount": 150000
  }
}

Response

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "message": "Agent updated successfully",
    "updated_at": "2025-12-15T11:00:00Z"
  }
}

Agent Health

Send Heartbeat

Agents should send periodic heartbeats to maintain health status.

POST /api/registry/agents/{agent_id}/heartbeat
X-API-Key: owkai_...
Content-Type: application/json

{
  "status": "healthy",
  "metrics": {
    "cpu_percent": 45,
    "memory_percent": 62,
    "active_tasks": 3,
    "queue_depth": 12
  },
  "version": "2.1.0"
}

Response

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "health_status": "healthy",
    "next_heartbeat_due": "2025-12-15T10:35:00Z"
  }
}

Get Health Status

GET /api/registry/agents/{agent_id}/health
X-API-Key: owkai_...

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "health_status": "healthy",
    "last_heartbeat": "2025-12-15T10:30:00Z",
    "uptime_percent": 99.9,
    "health_history": [
      {"timestamp": "2025-12-15T10:30:00Z", "status": "healthy"},
      {"timestamp": "2025-12-15T10:25:00Z", "status": "healthy"},
      {"timestamp": "2025-12-15T10:20:00Z", "status": "healthy"}
    ],
    "metrics": {
      "cpu_percent": 45,
      "memory_percent": 62
    }
  }
}

Trust Levels

Set Trust Level

PUT /api/registry/agents/{agent_id}/trust-level
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "trust_level": "elevated",
  "reason": "Agent has demonstrated consistent behavior over 30 days"
}

Trust Level Effects

Level	Auto-Approve	Max Risk Score	Description
`sandbox`	None	20	New/testing agents
`standard`	Low risk	40	Normal operation
`elevated`	Low/Medium	60	Trusted agents
`trusted`	Up to High	80	Fully trusted

Kill Switch

Activate Kill Switch

Immediately terminate agent's ability to execute actions.

POST /api/registry/agents/{agent_id}/emergency-suspend
Authorization: Bearer <admin_jwt>
X-CSRF-Token: <csrf_token>
Content-Type: application/json

{
  "reason": "Detected anomalous trading patterns",
  "notify_owner": true,
  "preserve_pending": false
}

Response

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "previous_status": "active",
    "new_status": "killed",
    "killed_at": "2025-12-15T11:00:00Z",
    "killed_by": "security@company.com",
    "reason": "Detected anomalous trading patterns",
    "pending_actions_cancelled": 5
  }
}

Reactivate Agent

POST /api/registry/agents/{agent_id}/activate
Authorization: Bearer <admin_jwt>
X-CSRF-Token: <csrf_token>
Content-Type: application/json

{
  "reason": "Investigation complete, false positive",
  "trust_level": "standard"
}

Agent Statistics

Get Statistics

GET /api/registry/agents/{agent_id}/usage?period=30d
X-API-Key: owkai_...

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "period": "30d",
    "statistics": {
      "total_actions": 5000,
      "approved": 4800,
      "denied": 150,
      "pending": 50,
      "approval_rate": 96.0,
      "avg_risk_score": 32,
      "avg_processing_time_ms": 45
    },
    "by_action_type": {
      "trade_execution": {"total": 3000, "approved": 2900},
      "market_analysis": {"total": 1500, "approved": 1500},
      "portfolio_rebalance": {"total": 500, "approved": 400}
    },
    "risk_distribution": {
      "low": 3500,
      "medium": 1200,
      "high": 250,
      "critical": 50
    }
  }
}

Delete Agent

Unregister an agent (soft delete).

DELETE /api/registry/agents/{agent_id}
Authorization: Bearer <admin_jwt>
X-CSRF-Token: <csrf_token>

{
  "status": "success",
  "data": {
    "agent_id": "trading-bot-001",
    "message": "Agent unregistered successfully",
    "deleted_at": "2025-12-15T12:00:00Z"
  }
}

SDK Examples

Python

from ascend import AscendClient

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

# Register agent
agent = client.register_agent(
    agent_id="my-agent",
    agent_type="data-processor",
    capabilities=["data_read", "data_write"]
)

# Send heartbeat
client.send_heartbeat(
    agent_id="my-agent",
    status="healthy",
    metrics={"cpu_percent": 30}
)

# Get agent status
status = client.get_agent("my-agent")
print(f"Health: {status.health.status}")

Node.js

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

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

// Register agent
const agent = await client.registerAgent({
  agentId: 'my-agent',
  agentType: 'data-processor',
  capabilities: ['data_read', 'data_write']
});

// Send heartbeat
await client.sendHeartbeat({
  agentId: 'my-agent',
  status: 'healthy',
  metrics: { cpuPercent: 30 }
});

Next Steps

Actions API - Submit actions
Kill Switch - Emergency controls
Trust Levels - Agent trust

Document Version: 1.0.0 | Last Updated: December 2025

Overview​

Base URL​

Register Agent​

Request​

Parameters​

Response​

Get Agent​

Request​

Response​

List Agents​

Request​

Query Parameters​

Response​

Update Agent​

Request​

Response​

Agent Health​

Send Heartbeat​

Response​

Get Health Status​

Trust Levels​

Set Trust Level​

Trust Level Effects​

Kill Switch​

Activate Kill Switch​

Response​

Reactivate Agent​

Agent Statistics​

Get Statistics​

Delete Agent​

SDK Examples​

Python​

Node.js​

Next Steps​

Overview

Base URL

Register Agent

Request

Parameters

Response

Get Agent

Request

Response

List Agents

Request

Query Parameters

Response

Update Agent

Request

Response

Agent Health

Send Heartbeat

Response

Get Health Status

Trust Levels

Set Trust Level

Trust Level Effects

Kill Switch

Activate Kill Switch

Response

Reactivate Agent

Agent Statistics

Get Statistics

Delete Agent

SDK Examples

Python

Node.js

Next Steps