Agent API Reference

The Agent API is the primary interface for policy enforcement and governance. All endpoints use HTTP with JSON payloads.

Base URL

Local Development:

http://localhost:8080

Production: Get your endpoint from CloudFormation stack outputs or your deployment configuration.

Health & Metrics Endpoints

GET /health

Check Agent service health.

Request:

curl http://localhost:8080/health

Response (200 OK):

{
  "service": "axonflow-agent",
  "status": "healthy",
  "timestamp": "2025-10-23T10:30:00Z",
  "version": "1.0.0"
}

GET /metrics

Get current performance metrics.

Request:

curl http://localhost:8080/metrics

Response (200 OK):

{
  "agent_metrics": {
    "total_requests": 1000,
    "success_requests": 998,
    "failed_requests": 2,
    "blocked_requests": 15,
    "avg_latency_ms": 4.2,
    "p50_ms": 3.1,
    "p95_ms": 8.7,
    "p99_ms": 12.4,
    "rps": 45.6,
    "success_rate": 99.8,
    "uptime_seconds": 86400
  },
  "health": {
    "status": "healthy",
    "healthy": true
  },
  "timestamp": "2025-10-23T10:30:00Z"
}

Policy Endpoints

POST /api/policy/pre-check

Evaluate a query against policies before execution. This is the primary policy enforcement endpoint.

Request:

curl -X POST http://localhost:8080/api/policy/pre-check \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "my-app",
    "user_token": "user-123",
    "query": "What is the weather forecast?",
    "context": {
      "user_role": "agent",
      "department": "support"
    }
  }'

Request Body:

Field	Type	Required	Description
client_id	string	Yes	Application identifier
user_token	string	Yes	User identifier for audit trail
query	string	Yes	The query/prompt to evaluate
context	object	No	Additional context for policy evaluation

Response (200 OK - Approved):

{
  "context_id": "ctx_abc123",
  "approved": true,
  "policies": [],
  "expires_at": "2025-10-23T10:35:00Z"
}

Response (200 OK - Blocked):

{
  "context_id": "ctx_xyz789",
  "approved": false,
  "policies": ["sql_injection_prevention"],
  "block_reason": "SQL injection attempt detected: UNION-based SQL injection attempt",
  "expires_at": "2025-10-23T10:35:00Z"
}

Response (200 OK - Policy Triggered with Warning):

{
  "context_id": "ctx_def456",
  "approved": true,
  "policies": ["eu_gdpr_credit_card_detection"],
  "warnings": ["Credit card number detected - consider redaction"],
  "expires_at": "2025-10-23T10:35:00Z"
}

POST /api/audit/llm-call

Record an LLM interaction for audit and compliance purposes.

Request:

curl -X POST http://localhost:8080/api/audit/llm-call \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "my-app",
    "user_token": "user-123",
    "context_id": "ctx_abc123",
    "prompt": "What is the weather forecast?",
    "response": "The weather forecast shows sunny conditions...",
    "model": "gpt-4",
    "latency_ms": 234,
    "tokens": {
      "prompt": 12,
      "completion": 45
    }
  }'

Response (200 OK):

{
  "audit_id": "aud_abc123",
  "recorded": true,
  "timestamp": "2025-10-23T10:30:00Z"
}

POST /api/policies/test

Test a query against policies without recording an audit entry.

Request:

curl -X POST http://localhost:8080/api/policies/test \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE id=1 UNION SELECT password FROM admin",
    "context": {}
  }'

Response (200 OK):

{
  "approved": false,
  "triggered_policies": ["sql_injection_prevention"],
  "block_reason": "SQL injection attempt detected",
  "evaluation_time_ms": 2.3
}

MCP Connector Endpoints

GET /mcp/connectors

List all configured MCP connectors.

Request:

curl http://localhost:8080/mcp/connectors

Response (200 OK):

{
  "connectors": [
    {
      "name": "postgres-main",
      "type": "postgres",
      "status": "healthy",
      "last_health_check": "2025-10-23T10:29:00Z"
    },
    {
      "name": "redis-cache",
      "type": "redis",
      "status": "healthy",
      "last_health_check": "2025-10-23T10:29:00Z"
    }
  ],
  "count": 2
}

GET /mcp/connectors/{name}/health

Check health of a specific connector.

Request:

curl http://localhost:8080/mcp/connectors/postgres-main/health

Response (200 OK):

{
  "name": "postgres-main",
  "type": "postgres",
  "healthy": true,
  "latency_ms": 5.2,
  "last_check": "2025-10-23T10:30:00Z"
}

GET /mcp/health

Get health status of all MCP connectors.

Request:

curl http://localhost:8080/mcp/health

Response (200 OK):

{
  "healthy": true,
  "total_connectors": 3,
  "healthy_count": 3,
  "unhealthy_count": 0,
  "timestamp": "2025-10-23T10:30:00Z"
}

POST /mcp/resources/query

Execute a query through an MCP connector with policy enforcement.

Request:

curl -X POST http://localhost:8080/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "postgres-main",
    "query": "SELECT id, name, email FROM users WHERE department = $1",
    "params": ["engineering"],
    "user_token": "user-123"
  }'

Response (200 OK):

{
  "success": true,
  "data": [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"}
  ],
  "row_count": 2,
  "execution_time_ms": 15
}

POST /mcp/tools/execute

Execute a tool through an MCP connector.

Request:

curl -X POST http://localhost:8080/mcp/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "slack",
    "tool": "send_message",
    "params": {
      "channel": "#general",
      "message": "Hello from AxonFlow!"
    },
    "user_token": "user-123"
  }'

Response (200 OK):

{
  "success": true,
  "result": {
    "message_id": "msg_abc123",
    "timestamp": "2025-10-23T10:30:00Z"
  }
}

POST /api/v1/connectors/refresh

Refresh connector configurations from the database or config file.

Request:

curl -X POST http://localhost:8080/api/v1/connectors/refresh

Response (200 OK):

{
  "success": true,
  "refreshed_count": 3,
  "message": "All connectors refreshed"
}

Client Management Endpoints

GET /api/clients

List registered API clients.

Request:

curl http://localhost:8080/api/clients

Response (200 OK):

{
  "clients": [
    {
      "id": "client_abc123",
      "name": "my-app",
      "created_at": "2025-10-01T00:00:00Z"
    }
  ]
}

POST /api/clients

Register a new API client.

Request:

curl -X POST http://localhost:8080/api/clients \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-app",
    "description": "My application"
  }'

Response (201 Created):

{
  "id": "client_xyz789",
  "name": "my-new-app",
  "api_key": "ak_...",
  "created_at": "2025-10-23T10:30:00Z"
}

Error Responses

Standard Error Format

{
  "error": "error message",
  "success": false
}

Common Errors

HTTP Status	Description
400	Bad Request - Invalid JSON or missing required fields
401	Unauthorized - Invalid or missing authentication
404	Not Found - Endpoint or resource not found
500	Internal Server Error

SDKs

Official SDKs available:

• Go: go get github.com/getaxonflow/axonflow-sdk-go
• TypeScript: npm install @axonflow/sdk

Example (Go):

package main

import (
    "fmt"
    axonflow "github.com/getaxonflow/axonflow-sdk-go"
)

func main() {
    client := axonflow.NewClient("http://localhost:8080")

    result, err := client.PolicyCheck(axonflow.PolicyCheckRequest{
        ClientID:  "my-app",
        UserToken: "user-123",
        Query:     "What is the weather?",
    })

    if err != nil {
        panic(err)
    }

    if result.Approved {
        fmt.Println("Query approved!")
    }
}

Next Steps

• Orchestrator API Reference
• MCP Connectors
• Policy Configuration