Register Agent

Register a new AI agent with the Ascend governance platform. Registered agents can submit actions for authorization and have configurable risk thresholds.

Endpoint

POST /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)
`Content-Type`	Yes	Must be `application/json`

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

Body

{
  "agent_id": "my-production-agent",
  "display_name": "Production Database Agent",
  "description": "Agent for automated database operations",
  "agent_type": "supervised",
  "default_risk_score": 50,
  "max_risk_threshold": 80,
  "auto_approve_below": 30,
  "requires_mfa_above": 70,
  "allowed_action_types": ["database_query", "database_read"],
  "allowed_resources": ["production-db", "staging-db"],
  "blocked_resources": ["customer-pii"],
  "is_mcp_server": false,
  "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",
    "owner": "data-team@company.com"
  }
}

Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Unique identifier (3-64 chars)
`display_name`	string	Yes	Human-readable name (max 255 chars)
`description`	string	No	Agent description
`agent_type`	string	No	Type: `autonomous`, `supervised`, `advisory`, `mcp_server`, `custom` (default: `supervised`)
`default_risk_score`	integer	No	Default risk score 0-100 (default: 50)
`max_risk_threshold`	integer	No	Risk threshold requiring approval (default: 80)
`auto_approve_below`	integer	No	Auto-approve actions below this score (default: 30)
`requires_mfa_above`	integer	No	Require MFA for approval above this score (default: 70)
`allowed_action_types`	array	No	Allowed action types
`allowed_resources`	array	No	Allowed resource targets
`blocked_resources`	array	No	Blocked resource targets
`is_mcp_server`	boolean	No	Whether this is an MCP server (default: false)
`mcp_server_url`	string	No	MCP server URL (if MCP server)
`mcp_capabilities`	object	No	MCP capabilities configuration
`alert_on_high_risk`	boolean	No	Send alerts for high-risk actions (default: true)
`alert_recipients`	array	No	Email addresses for alerts
`webhook_url`	string	No	Webhook URL for notifications
`tags`	array	No	Tags for organization
`metadata`	object	No	Custom metadata

Agent Types

Type	Description	Default Thresholds
`supervised`	Human oversight required for risky actions	auto_approve < 30, require_approval >= 80
`autonomous`	Can operate independently with stricter limits	auto_approve < 20, require_approval >= 60
`advisory`	Read-only agent for analysis	auto_approve < 40, require_approval >= 90
`mcp_server`	MCP-compatible server registration	Configurable per tool
`custom`	Custom configuration	User-defined

Response

Success (201 Created)

{
  "success": true,
  "created": true,
  "agent": {
    "id": 123,
    "agent_id": "my-production-agent",
    "display_name": "Production Database Agent",
    "status": "draft",
    "version": "1.0.0",
    "agent_type": "supervised",
    "created_at": "2026-01-20T14:30:52Z",
    "organization_id": 1
  },
  "message": "Agent registered: my-production-agent",
  "next_steps": [
    "Configure policies using POST /api/registry/agents/{id}/policies",
    "Activate agent using POST /api/registry/agents/{id}/activate",
    "Submit actions using POST /api/v1/actions/submit"
  ]
}

Already Exists (200 OK)

If the agent already exists:

{
  "success": true,
  "created": false,
  "agent": {
    "id": 123,
    "agent_id": "my-production-agent",
    "display_name": "Production Database Agent",
    "status": "active",
    "version": "1.2.0",
    "agent_type": "supervised",
    "created_at": "2026-01-15T10:00:00Z",
    "organization_id": 1
  },
  "message": "Agent already exists: my-production-agent"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`created`	boolean	Whether a new agent was created
`agent.id`	integer	Internal database ID
`agent.agent_id`	string	Your unique agent identifier
`agent.display_name`	string	Human-readable name
`agent.status`	string	`draft`, `active`, or `suspended`
`agent.version`	string	Semantic version of configuration
`agent.agent_type`	string	Agent type
`agent.created_at`	string	ISO 8601 creation timestamp
`agent.organization_id`	integer	Organization ID
`message`	string	Status message
`next_steps`	array	Recommended next actions

Agent Status Values

Status	Description	Can Submit Actions
`draft`	Newly registered, not yet activated	No
`active`	Activated and operational	Yes
`suspended`	Suspended by admin or auto-suspension	No

Errors

Code	Description
400	Bad request - validation error
401	Unauthorized - missing or invalid credentials
409	Conflict - agent_id already exists
500	Internal server error

Validation Error (400):

{
  "detail": "agent_id must be 3-64 characters",
  "error_code": "VALIDATION_ERROR",
  "status": 400
}

Agent Lifecycle

Register - Agent is created in draft status
Configure - Add policies and settings
Activate - Admin activates agent (POST /api/registry/agents/{id}/activate)
Operate - Agent can submit actions
Suspend - Admin or auto-suspend disables agent

Examples

cURL

curl -X POST https://pilot.owkai.app/api/registry/agents \
  -H "X-API-Key: owkai_admin_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-production-agent",
    "display_name": "Production Database Agent",
    "description": "Agent for automated database operations",
    "agent_type": "supervised",
    "auto_approve_below": 30,
    "max_risk_threshold": 80,
    "allowed_action_types": ["database_query", "database_read"],
    "tags": ["production", "database"]
  }'

Python

from ascend import AscendClient

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

# Register a new agent
result = client.agents.register(
    agent_id="my-production-agent",
    display_name="Production Database Agent",
    description="Agent for automated database operations",
    agent_type="supervised",
    auto_approve_below=30,
    max_risk_threshold=80,
    allowed_action_types=["database_query", "database_read"],
    tags=["production", "database"]
)

if result.created:
    print(f"New agent registered: {result.agent.agent_id}")
else:
    print(f"Agent already exists: {result.agent.agent_id}")

Node.js

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

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

const result = await client.agents.register({
  agentId: 'my-production-agent',
  displayName: 'Production Database Agent',
  description: 'Agent for automated database operations',
  agentType: 'supervised',
  autoApproveBelow: 30,
  maxRiskThreshold: 80,
  allowedActionTypes: ['database_query', 'database_read'],
  tags: ['production', 'database']
});

console.log(`Agent status: ${result.agent.status}`);

Python (requests)

import requests

response = requests.post(
    "https://pilot.owkai.app/api/registry/agents",
    headers={
        "X-API-Key": "owkai_admin_...",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "my-production-agent",
        "display_name": "Production Database Agent",
        "description": "Agent for automated database operations",
        "agent_type": "supervised",
        "auto_approve_below": 30,
        "max_risk_threshold": 80,
        "allowed_action_types": ["database_query", "database_read"]
    }
)

result = response.json()
print(f"Created: {result['created']}")
print(f"Status: {result['agent']['status']}")

After Registration

After registering an agent:

1. Add Policies

curl -X POST https://pilot.owkai.app/api/registry/agents/my-production-agent/policies \
  -H "X-API-Key: owkai_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "Block PII Access",
    "policy_description": "Block access to PII data",
    "policy_action": "block",
    "conditions": {"resource_contains": "pii"},
    "priority": 100
  }'

2. Activate the Agent

curl -X POST https://pilot.owkai.app/api/registry/agents/my-production-agent/activate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."

3. Submit Actions

curl -X POST https://pilot.owkai.app/api/v1/actions/submit \
  -H "X-API-Key: owkai_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-production-agent",
    "action_type": "database_query",
    "description": "Query user data",
    "tool_name": "postgresql"
  }'

List Agents - List all registered agents

Endpoint​

Authentication​

Request​

Headers​

Body​

Parameters​

Agent Types​

Response​

Success (201 Created)​

Already Exists (200 OK)​

Response Fields​

Agent Status Values​

Errors​

Agent Lifecycle​

Examples​

cURL​

Python​

Node.js​

Python (requests)​

After Registration​

1. Add Policies​

2. Activate the Agent​

3. Submit Actions​

Related Endpoints​