Agents API

Field	Value
Document ID	ASCEND-API-002
Version	2026.04
Last Updated	April 2026
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.

note

Agent registration and management endpoints require admin-level API keys. Standard agent keys can only read their own agent record and submit heartbeats.

Base URL

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

Register Agent

Register a new agent with ASCEND.

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.3.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.3.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/agents/health/{agent_id}
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"
  }
}

Kill-switch HTTP fallback (SEC-103, SDK 2.3.0)

The primary kill-switch channel is SNS/SQS — the backend publishes BLOCK / UNBLOCK / SUSPEND / RESUME / RATE_LIMIT / QUARANTINE commands to per-organization queues, and agents receive them via long-poll. For environments where the SDK cannot hold AWS credentials or SQS is unreachable, two HTTP fallback endpoints are available.

List pending commands

GET /api/registry/agents/{agent_id}/commands
Authorization: Bearer <admin_jwt_or_api_key>

Returns pending + delivered commands for this agent PLUS org-broadcast commands (commands with agent_id=null on the record).

{
  "agent_id": "trading-bot-001",
  "count": 1,
  "commands": [
    {
      "command_id": "a1b2c3d4-...",
      "command_type": "BLOCK",
      "target_type": "agent",
      "reason": "Anomalous trade volume detected",
      "parameters": {},
      "status": "delivered",
      "issued_by": "admin@company.com",
      "issued_via": "dashboard",
      "created_at": "2026-04-17T10:00:00Z",
      "expires_at": null,
      "is_broadcast": false
    }
  ]
}

Auth: admin role (JWT or API key). The target agent_id must belong to the caller's organization — off-tenant or unknown agents return HTTP 404. Off-tenant command records return HTTP 403 (not 404) to prevent cross-tenant enumeration.

Acknowledge a command

Receipt-only acknowledgement — records that the command has been received by the agent. Does not record command outcome.

POST /api/registry/agents/{agent_id}/commands/{command_id}/ack
Authorization: Bearer <admin_jwt_or_api_key>
Content-Type: application/json

{}

Response:

{
  "success": true,
  "command_id": "a1b2c3d4-...",
  "status": "acknowledged"
}

Fail-secure rules:

Condition	Response	Audit
command_id not found OR in a different organization	HTTP 403 "Command not accessible from this tenant"	AGENT_COMMAND_ACK_REJECTED (HIGH)
Command targets a different agent_id (non-broadcast)	HTTP 403 "Command is not targeted at this agent"	AGENT_COMMAND_ACK_REJECTED (HIGH)
Successful ack	HTTP 200	AGENT_COMMAND_ACKNOWLEDGED (MEDIUM)

Broadcast commands (where agent_id=null on the command record) can be ack'd by any agent in the organization.

SDK 2.3.0

Use AscendClient.get_pending_commands(agent_id) and AscendClient.ack_command(command_id, agent_id). See Python SDK — SDK 2.3.0 section.

Related REST additions (SDK 2.3.0)

• POST /api/v1/supply-chain/components — dual-auth (JWT admin OR API-key admin). See AI Supply Chain.
• PUT /api/registry/agents/{agent_id} now honors a model_id field to link a DeployedModel. See AI Model Registry.
• POST /api/v1/actions/submit now honors three optional orchestration fields (orchestration_session_id, parent_action_id, orchestration_depth). See Multi-Agent Orchestration.

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('@ascend-ai/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: 2026.04 | Last Updated: April 2026