Documentation

API Reference

Complete reference for perfecX Agent REST API endpoints and SDK methods.

Base URL

https://api.perfecxion.ai/v1

Authentication

All API requests require authentication using an API key.

# HTTP Header
Authorization: Bearer YOUR_API_KEY

# Example with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.perfecxion.ai/v1/agents

Agent Management

Register Agent

POST/agents

Request Body

{
  "agent_id": "my-agent-001",
  "name": "Customer Support Agent",
  "framework": "langchain",
  "version": "1.0.0",
  "capabilities": ["chat", "tool_use", "memory"],
  "metadata": {
    "team": "support",
    "environment": "production"
  }
}

Response

{
  "agent_id": "my-agent-001",
  "registration_token": "agt_1234567890abcdef",
  "monitoring_endpoint": "wss://monitor.perfecxion.ai/agents/my-agent-001",
  "created_at": "2024-01-15T10:30:00Z"
}

List Agents

GET/agents

Retrieve a list of all registered agents.

Query Parameters

status - Filter by agent status (active, inactive, error)
framework - Filter by framework (langchain, autogpt, crewai)
limit - Number of results per page (default: 20)
offset - Pagination offset

Update Agent

PUT/agents/{agent_id}

Update agent configuration and metadata.

Delete Agent

DELETE/agents/{agent_id}

Unregister an agent and stop monitoring.

Monitoring & Analytics

Send Event

POST/agents/{agent_id}/events

Send agent activity events for monitoring.

{
  "event_type": "tool_execution",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "tool": "web_search",
    "input": "latest AI security news",
    "output": "Found 5 relevant articles...",
    "duration_ms": 1250,
    "success": true
  },
  "context": {
    "session_id": "sess_123",
    "user_id": "user_456"
  }
}

Get Metrics

GET/agents/{agent_id}/metrics

Retrieve performance and security metrics.

{
  "agent_id": "my-agent-001",
  "time_range": {
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-15T10:00:00Z"
  },
  "metrics": {
    "total_requests": 1523,
    "average_response_time_ms": 245,
    "error_rate": 0.02,
    "anomaly_score": 0.15,
    "policy_violations": 3,
    "security_events": {
      "memory_tampering_attempts": 0,
      "unauthorized_tool_access": 1,
      "suspicious_patterns": 2
    }
  }
}

Get Anomalies

GET/agents/{agent_id}/anomalies

Retrieve detected behavioral anomalies.

Security Policies

Create Policy

POST/policies

Create a new security policy for agents.

{
  "name": "production-safety-policy",
  "description": "Safety policy for production agents",
  "rules": [
    {
      "type": "tool_restriction",
      "allowed_tools": ["web_search", "calculator", "file_reader"],
      "forbidden_tools": ["code_executor", "system_command"]
    },
    {
      "type": "execution_limit",
      "max_execution_time_ms": 300000,
      "max_memory_mb": 512
    },
    {
      "type": "content_filter",
      "forbidden_patterns": ["rm -rf", "DROP TABLE", "DELETE FROM"],
      "sensitive_data_detection": true
    }
  ],
  "enforcement": "strict"
}

Apply Policy to Agent

POST/agents/{agent_id}/policies

Apply security policies to an agent.

WebSocket API

Real-time monitoring and control via WebSocket connection.

// JavaScript WebSocket example
const ws = new WebSocket('wss://monitor.perfecxion.ai/agents/my-agent-001');

ws.on('open', () => {
  // Send authentication
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'agt_1234567890abcdef'
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  
  switch(event.type) {
    case 'anomaly_detected':
      console.warn('Anomaly detected:', event.data);
      break;
    case 'policy_violation':
      console.error('Policy violation:', event.data);
      break;
    case 'metrics_update':
      console.log('Metrics:', event.data);
      break;
  }
});

Rate Limits

Endpoint	Rate Limit
Agent Registration	100 per hour
Event Ingestion	10,000 per minute
Metrics Retrieval	1,000 per hour
Policy Management	100 per hour

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

SDK Documentation

Python SDK Documentation Node.js SDK Documentation