REST Endpoints

Complete REST API reference for the Pixell Agent Runtime (PAR). All endpoints support JSON request/response format with comprehensive error handling and authentication.

Base URL

http://localhost:8080

Authentication

API Key Authentication

# Include API key in header
curl -H "X-API-Key: your-secret-key" http://localhost:8080/health

JWT Token Authentication

# Include JWT token in header
curl -H "Authorization: Bearer your-jwt-token" http://localhost:8080/agents

Common Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "details": "Missing required field: 'message'"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

Health & Status Endpoints

Health Check

Check if PAR is running and healthy.

GET /health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "runtime": "three-surface",
    "version": "0.1.0",
    "uptime": "00:05:23",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Runtime Status

Get detailed runtime information.

GET /status

Response:

{
  "success": true,
  "data": {
    "runtime": {
      "mode": "three-surface",
      "version": "0.1.0",
      "uptime": "00:05:23",
      "memory_usage": "256MB",
      "cpu_usage": "15%"
    },
    "server": {
      "host": "localhost",
      "port": 8080,
      "admin_port": 9090
    }
  }
}

Agent Endpoints (Three-Surface Mode)

Agent Status

Get status of the running agent.

GET /agent/status

Response:

{
  "success": true,
  "data": {
    "agent": {
      "name": "my-agent",
      "version": "0.1.0",
      "status": "running",
      "capabilities": ["greeting", "conversation"],
      "uptime": "00:05:23"
    }
  }
}

Agent Capabilities

Get agent capabilities and endpoints.

GET /agent/capabilities

Response:

{
  "success": true,
  "data": {
    "capabilities": [
      "greeting",
      "conversation",
      "personalization"
    ],
    "endpoints": {
      "rest": ["/greet", "/chat", "/health"],
      "a2a": ["GreetingService.Greet", "GreetingService.Chat"],
      "ui": ["/"]
    }
  }
}

Invoke Agent

Send a message to the agent.

POST /agent/invoke
Content-Type: application/json

{
  "message": "Hello, agent!",
  "context": {
    "user_id": "user123",
    "session_id": "session456"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "Hello! How can I help you today?",
    "agent": "my-agent",
    "version": "0.1.0",
    "processing_time": "0.123s"
  }
}

Agent Health

Check agent-specific health.

GET /agent/health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "agent": "my-agent",
    "last_request": "2024-01-15T10:29:45Z",
    "response_time": "0.123s"
  }
}

Platform Endpoints (Multi-Agent Mode)

Platform Status

Get platform status and statistics.

GET /platform/status

Response:

{
  "success": true,
  "data": {
    "platform": {
      "mode": "multi-agent",
      "max_agents": 20,
      "active_agents": 3,
      "status": "healthy"
    },
    "agents": [
      {
        "id": "agent-1",
        "name": "greeting-agent",
        "status": "running",
        "uptime": "00:05:23"
      },
      {
        "id": "agent-2", 
        "name": "chat-agent",
        "status": "running",
        "uptime": "00:03:15"
      }
    ]
  }
}

List Agents

Get list of all deployed agents.

GET /agents

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent-1",
        "name": "greeting-agent",
        "version": "0.1.0",
        "status": "running",
        "created_at": "2024-01-15T10:25:00Z",
        "uptime": "00:05:23"
      },
      {
        "id": "agent-2",
        "name": "chat-agent", 
        "version": "0.2.0",
        "status": "running",
        "created_at": "2024-01-15T10:27:00Z",
        "uptime": "00:03:15"
      }
    ],
    "total": 2,
    "active": 2
  }
}

Deploy Agent

Deploy a new agent to the platform.

POST /agents
Content-Type: application/json

{
  "name": "new-agent",
  "package": "base64-encoded-apkg-data",
  "config": {
    "memory_limit": "512MB",
    "timeout": 30
  }
}

Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent-3",
      "name": "new-agent",
      "status": "deploying",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "deployment_id": "deploy_123456789"
  }
}

Get Agent Details

Get detailed information about a specific agent.

GET /agents/{agent_id}

Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent-1",
      "name": "greeting-agent",
      "version": "0.1.0",
      "status": "running",
      "capabilities": ["greeting", "conversation"],
      "created_at": "2024-01-15T10:25:00Z",
      "uptime": "00:05:23",
      "memory_usage": "128MB",
      "request_count": 42
    }
  }
}

Update Agent

Update agent configuration.

PUT /agents/{agent_id}
Content-Type: application/json

{
  "config": {
    "memory_limit": "1GB",
    "timeout": 60
  }
}

Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent-1",
      "name": "greeting-agent",
      "status": "updating",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}

Delete Agent

Remove an agent from the platform.

DELETE /agents/{agent_id}

Response:

{
  "success": true,
  "data": {
    "message": "Agent deleted successfully",
    "agent_id": "agent-1"
  }
}

Invoke Specific Agent

Send a message to a specific agent.

POST /agents/{agent_id}/invoke
Content-Type: application/json

{
  "message": "Hello, specific agent!",
  "context": {
    "user_id": "user123"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "Hello! I'm the specific agent.",
    "agent": "greeting-agent",
    "processing_time": "0.123s"
  }
}

Monitoring Endpoints

Metrics

Get runtime metrics and statistics.

GET /metrics

Response:

{
  "success": true,
  "data": {
    "runtime": {
      "uptime": "00:05:23",
      "memory_usage": "256MB",
      "cpu_usage": "15%",
      "request_count": 42,
      "error_count": 0
    },
    "agents": [
      {
        "id": "agent-1",
        "request_count": 25,
        "error_count": 0,
        "avg_response_time": "0.123s"
      }
    ]
  }
}

Logs

Get recent log entries.

GET /logs?level=INFO&limit=100

Response:

{
  "success": true,
  "data": {
    "logs": [
      {
        "timestamp": "2024-01-15T10:30:00Z",
        "level": "INFO",
        "message": "Agent request processed",
        "agent_id": "agent-1",
        "request_id": "req_123456789"
      }
    ],
    "total": 100,
    "level": "INFO"
  }
}

Error Handling

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`429`	Rate Limited
`500`	Internal Server Error

Error Codes

Code	Description
`INVALID_REQUEST`	Invalid request parameters
`UNAUTHORIZED`	Missing or invalid authentication
`AGENT_NOT_FOUND`	Agent not found
`AGENT_ERROR`	Agent processing error
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Internal server error

Error Examples

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: 'message'",
    "details": "The 'message' field is required for agent invocation"
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "Include X-API-Key header with valid key"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent not found",
    "details": "Agent with ID 'agent-999' does not exist"
  }
}

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248600

Rate Limit Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": "Too many requests. Try again in 60 seconds."
  }
}

Request/Response Examples

Complete Agent Invocation

# Request
curl -X POST http://localhost:8080/agent/invoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{
    "message": "Hello, agent!",
    "context": {
      "user_id": "user123",
      "session_id": "session456",
      "language": "en"
    }
  }'

# Response
{
  "success": true,
  "data": {
    "response": "Hello! How can I help you today?",
    "agent": "my-agent",
    "version": "0.1.0",
    "processing_time": "0.123s",
    "context": {
      "user_id": "user123",
      "session_id": "session456"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

Agent Deployment

# Request
curl -X POST http://localhost:8080/agents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{
    "name": "new-agent",
    "package": "base64-encoded-apkg-data",
    "config": {
      "memory_limit": "512MB",
      "timeout": 30,
      "auto_restart": true
    }
  }'

# Response
{
  "success": true,
  "data": {
    "agent": {
      "id": "agent-3",
      "name": "new-agent",
      "status": "deploying",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "deployment_id": "deploy_123456789",
    "estimated_deployment_time": "30s"
  }
}

SDK Examples

Python SDK

import requests

# Initialize client
client = requests.Session()
client.headers.update({
    'X-API-Key': 'your-secret-key',
    'Content-Type': 'application/json'
})

# Invoke agent
response = client.post('http://localhost:8080/agent/invoke', json={
    'message': 'Hello, agent!',
    'context': {'user_id': 'user123'}
})

result = response.json()
print(result['data']['response'])

JavaScript SDK

// Initialize client
const client = axios.create({
  baseURL: 'http://localhost:8080',
  headers: {
    'X-API-Key': 'your-secret-key',
    'Content-Type': 'application/json'
  }
});

// Invoke agent
const response = await client.post('/agent/invoke', {
  message: 'Hello, agent!',
  context: { user_id: 'user123' }
});

console.log(response.data.data.response);

Testing Endpoints

Health Check Test

# Test basic health
curl http://localhost:8080/health

# Test with authentication
curl -H "X-API-Key: your-secret-key" http://localhost:8080/health

Agent Invocation Test

# Test agent invocation
curl -X POST http://localhost:8080/agent/invoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"message": "Test message"}'

Platform Test

# Test platform status
curl -H "X-API-Key: your-secret-key" http://localhost:8080/platform/status

# Test agent listing
curl -H "X-API-Key: your-secret-key" http://localhost:8080/agents

Next Steps

After exploring the REST API:

gRPC Interface - Use A2A communication
Deployment - Deploy to production
Configuration - Advanced configuration options

Ready for A2A communication? Check out gRPC Interface to learn about agent-to-agent communication!

Base URL​

Authentication​

API Key Authentication​

JWT Token Authentication​

Common Response Format​

Success Response​

Error Response​

Health & Status Endpoints​

Health Check​

Runtime Status​

Agent Endpoints (Three-Surface Mode)​

Agent Status​

Agent Capabilities​

Invoke Agent​

Agent Health​

Platform Endpoints (Multi-Agent Mode)​

Platform Status​

List Agents​

Deploy Agent​

Get Agent Details​

Update Agent​

Delete Agent​

Invoke Specific Agent​

Monitoring Endpoints​

Metrics​

Logs​

Error Handling​

HTTP Status Codes​

Error Codes​

Error Examples​

400 Bad Request​

401 Unauthorized​

404 Not Found​

Rate Limiting​

Rate Limit Headers​

Rate Limit Response​

Request/Response Examples​

Complete Agent Invocation​

Agent Deployment​

SDK Examples​

Python SDK​

JavaScript SDK​

Testing Endpoints​

Health Check Test​

Agent Invocation Test​

Platform Test​

Next Steps​

Base URL

Authentication

API Key Authentication

JWT Token Authentication

Common Response Format

Success Response

Error Response

Health & Status Endpoints

Health Check

Runtime Status

Agent Endpoints (Three-Surface Mode)

Agent Status

Agent Capabilities

Invoke Agent

Agent Health

Platform Endpoints (Multi-Agent Mode)

Platform Status

List Agents

Deploy Agent

Get Agent Details

Update Agent

Delete Agent

Invoke Specific Agent

Monitoring Endpoints

Metrics

Logs

Error Handling

HTTP Status Codes

Error Codes

Error Examples

400 Bad Request

401 Unauthorized

404 Not Found

Rate Limiting

Rate Limit Headers

Rate Limit Response

Request/Response Examples

Complete Agent Invocation

Agent Deployment

SDK Examples

Python SDK

JavaScript SDK

Testing Endpoints

Health Check Test

Agent Invocation Test

Platform Test

Next Steps