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

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.

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

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​

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

List pending commands​

Acknowledge a command​

SDK 2.3.0​

Related REST additions (SDK 2.3.0)​

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

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

List pending commands

Acknowledge a command

SDK 2.3.0

Related REST additions (SDK 2.3.0)

SDK Examples

Python

Node.js

Next Steps