List Agents

Retrieve a list of all registered agents for your organization with filtering and pagination.

Endpoint

GET /api/registry/agents

Authentication

This endpoint supports both authentication methods:

API Key: X-API-Key header
JWT Token: Authorization: Bearer <token> header

Request

Headers

Header	Required	Description
`X-API-Key`	Yes*	Your API key
`Authorization`	Yes*	Bearer token (alternative to X-API-Key)

*One of X-API-Key or Authorization is required.

Query Parameters

Parameter	Type	Default	Description
`status_filter`	string	(none)	Filter by status: `draft`, `active`, `suspended`
`type_filter`	string	(none)	Filter by agent type: `autonomous`, `supervised`, `advisory`, `mcp_server`
`limit`	integer	100	Maximum results (max: 500)
`offset`	integer	0	Number of results to skip

Response

Success (200 OK)

{
  "success": true,
  "agents": [
    {
      "id": 123,
      "agent_id": "my-production-agent",
      "display_name": "Production Database Agent",
      "description": "Agent for automated database operations",
      "agent_type": "supervised",
      "status": "active",
      "version": "1.2.0",
      "default_risk_score": 50,
      "auto_approve_below": 30,
      "max_risk_threshold": 80,
      "is_mcp_server": false,
      "tags": ["production", "database"],
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": 124,
      "agent_id": "security-scanner",
      "display_name": "Security Scanner Agent",
      "description": "Autonomous security scanning agent",
      "agent_type": "autonomous",
      "status": "active",
      "version": "2.0.0",
      "default_risk_score": 60,
      "auto_approve_below": 20,
      "max_risk_threshold": 60,
      "is_mcp_server": false,
      "tags": ["security", "scanner"],
      "created_at": "2026-01-10T08:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`agents`	array	List of agent objects
`agents[].id`	integer	Internal database ID
`agents[].agent_id`	string	Unique agent identifier
`agents[].display_name`	string	Human-readable name
`agents[].description`	string	Agent description
`agents[].agent_type`	string	Agent type
`agents[].status`	string	Current status
`agents[].version`	string	Configuration version
`agents[].default_risk_score`	integer	Default risk score
`agents[].auto_approve_below`	integer	Auto-approve threshold
`agents[].max_risk_threshold`	integer	Max risk requiring approval
`agents[].is_mcp_server`	boolean	Whether this is an MCP server
`agents[].tags`	array	Agent tags
`agents[].created_at`	string	ISO 8601 creation timestamp
`pagination.total`	integer	Total number of agents
`pagination.limit`	integer	Current page limit
`pagination.offset`	integer	Current offset
`pagination.has_more`	boolean	Whether more results exist

Errors

Code	Description
401	Unauthorized - missing or invalid credentials
500	Internal server error

Examples

cURL

# List all agents
curl -X GET https://pilot.owkai.app/api/registry/agents \
  -H "X-API-Key: owkai_admin_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789"

# Filter by status
curl -X GET "https://pilot.owkai.app/api/registry/agents?status_filter=active" \
  -H "X-API-Key: owkai_admin_..."

# Filter by type with pagination
curl -X GET "https://pilot.owkai.app/api/registry/agents?type_filter=autonomous&limit=10&offset=0" \
  -H "X-API-Key: owkai_admin_..."

Python

from ascend import AscendClient

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

# List all agents
agents = client.agents.list()
print(f"Total agents: {agents.pagination.total}")

for agent in agents.agents:
    print(f"- {agent.agent_id}: {agent.status}")

# Filter by status
active_agents = client.agents.list(status_filter="active")

# Filter by type
autonomous_agents = client.agents.list(type_filter="autonomous")

# Paginate through all agents
offset = 0
limit = 50
all_agents = []

while True:
    result = client.agents.list(limit=limit, offset=offset)
    all_agents.extend(result.agents)

    if not result.pagination.has_more:
        break
    offset += limit

Node.js

import { AscendClient } from '@ascend-ai/sdk';

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

// List all agents
const agents = await client.agents.list();
console.log(`Total agents: ${agents.pagination.total}`);

agents.agents.forEach(agent => {
  console.log(`- ${agent.agentId}: ${agent.status}`);
});

// Filter by status
const activeAgents = await client.agents.list({ statusFilter: 'active' });

// Filter by type
const autonomousAgents = await client.agents.list({ typeFilter: 'autonomous' });

Python (requests)

import requests

# List all active agents
response = requests.get(
    "https://pilot.owkai.app/api/registry/agents",
    headers={"X-API-Key": "owkai_admin_..."},
    params={
        "status_filter": "active",
        "limit": 50,
        "offset": 0
    }
)

result = response.json()
print(f"Found {result['pagination']['total']} agents")

for agent in result["agents"]:
    print(f"Agent: {agent['agent_id']}")
    print(f"  Type: {agent['agent_type']}")
    print(f"  Status: {agent['status']}")
    print(f"  Risk Threshold: {agent['max_risk_threshold']}")

Filtering Examples

List Active Supervised Agents

curl -X GET "https://pilot.owkai.app/api/registry/agents?status_filter=active&type_filter=supervised" \
  -H "X-API-Key: owkai_admin_..."

List Suspended Agents

curl -X GET "https://pilot.owkai.app/api/registry/agents?status_filter=suspended" \
  -H "X-API-Key: owkai_admin_..."

List MCP Servers

curl -X GET "https://pilot.owkai.app/api/registry/agents?type_filter=mcp_server" \
  -H "X-API-Key: owkai_admin_..."

Get Single Agent

To get detailed information about a specific agent:

GET /api/registry/agents/{agent_id}

Example:

curl -X GET https://pilot.owkai.app/api/registry/agents/my-production-agent \
  -H "X-API-Key: owkai_admin_..."

Response:

{
  "success": true,
  "agent": {
    "id": 123,
    "agent_id": "my-production-agent",
    "display_name": "Production Database Agent",
    "description": "Agent for automated database operations",
    "agent_type": "supervised",
    "status": "active",
    "version": "1.2.0",

    "risk_config": {
      "default_risk_score": 50,
      "max_risk_threshold": 80,
      "auto_approve_below": 30,
      "requires_mfa_above": 70,
      "autonomous_auto_approve_below": 20,
      "autonomous_max_risk_threshold": 60
    },

    "capabilities": {
      "allowed_action_types": ["database_query", "database_read"],
      "allowed_resources": ["production-db", "staging-db"],
      "blocked_resources": ["customer-pii"]
    },

    "mcp_integration": {
      "is_mcp_server": false,
      "mcp_server_url": null,
      "mcp_capabilities": {}
    },

    "notifications": {
      "alert_on_high_risk": true,
      "alert_recipients": ["security@company.com"],
      "webhook_url": "https://your-server.com/webhooks/ascend"
    },

    "tags": ["production", "database"],
    "metadata": {"team": "data-engineering"},

    "audit": {
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "admin@company.com",
      "updated_at": "2026-01-18T14:30:00Z",
      "updated_by": "admin@company.com",
      "approved_at": "2026-01-15T12:00:00Z",
      "approved_by": "security@company.com"
    }
  }
}

Endpoint​

Authentication​

Request​

Headers​

Query Parameters​

Response​

Success (200 OK)​

Response Fields​

Errors​

Examples​

cURL​

Python​

Node.js​

Python (requests)​

Filtering Examples​

List Active Supervised Agents​

List Suspended Agents​

List MCP Servers​

Get Single Agent​

Related Endpoints​