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. Includes readiness status for orchestration.

Request:

curl http://localhost:8080/health

Response (200 OK):

{
  "service": "axonflow-agent",
  "status": "healthy",
  "ready": true,
  "timestamp": "2025-01-02T10:30:00Z",
  "version": "2.5.0",
  "components": {
    "database": "connected",
    "mcp_registry": "initialized",
    "policy_engine": "ready"
  }
}

GET /metrics

Get current performance metrics in JSON format.

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-01-02T10:30:00Z"
}

GET /prometheus

Get metrics in Prometheus format for scraping.

Request:

curl http://localhost:8080/prometheus

Response (200 OK):

# HELP axonflow_agent_requests_total Total number of requests processed
# TYPE axonflow_agent_requests_total counter
axonflow_agent_requests_total{status="success"} 998
axonflow_agent_requests_total{status="failed"} 2
axonflow_agent_requests_total{status="blocked"} 15

# HELP axonflow_agent_request_duration_seconds Request duration in seconds
# TYPE axonflow_agent_request_duration_seconds histogram
axonflow_agent_request_duration_seconds_bucket{le="0.005"} 850
axonflow_agent_request_duration_seconds_bucket{le="0.01"} 950
axonflow_agent_request_duration_seconds_bucket{le="0.025"} 990
axonflow_agent_request_duration_seconds_bucket{le="+Inf"} 1000

# HELP axonflow_agent_policy_evaluations_total Policy evaluation counts
# TYPE axonflow_agent_policy_evaluations_total counter
axonflow_agent_policy_evaluations_total{policy="sql_injection",result="pass"} 985
axonflow_agent_policy_evaluations_total{policy="sql_injection",result="block"} 15

Prometheus Integration

Configure Prometheus to scrape /prometheus for production monitoring. See Monitoring Overview for setup details.

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,
  "connector": "postgres-main",
  "data": [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"}
  ],
  "row_count": 2,
  "duration_ms": 15,
  "redacted": false,
  "redacted_fields": [],
  "policy_info": {
    "policies_evaluated": 12,
    "blocked": false,
    "redactions_applied": 0,
    "processing_time_ms": 2,
    "matched_policies": [],
    "exfiltration_check": {
      "exceeded": false,
      "rows_returned": 2,
      "row_limit": 10000,
      "bytes_returned": 156,
      "byte_limit": 10485760
    },
    "dynamic_policy_info": {
      "enabled": false,
      "evaluated": false
    }
  }
}

Response with Redaction (200 OK):

When PII is detected in the response, fields are redacted:

{
  "success": true,
  "connector": "postgres-main",
  "data": [
    {"id": 1, "name": "Alice", "ssn": "[REDACTED]", "email": "[email protected]"}
  ],
  "row_count": 1,
  "duration_ms": 18,
  "redacted": true,
  "redacted_fields": ["data[0].ssn"],
  "policy_info": {
    "policies_evaluated": 12,
    "blocked": false,
    "redactions_applied": 1,
    "processing_time_ms": 3,
    "matched_policies": [
      {
        "policy_id": "pii-us-ssn",
        "policy_name": "US Social Security Number",
        "category": "pii-us",
        "severity": "critical",
        "action": "redact"
      }
    ],
    "exfiltration_check": {
      "exceeded": false,
      "rows_returned": 1,
      "row_limit": 10000,
      "bytes_returned": 82,
      "byte_limit": 10485760
    },
    "dynamic_policy_info": {
      "enabled": false,
      "evaluated": false
    }
  }
}

Response (403 Forbidden):

When a query is blocked by security policy (e.g., SQL injection):

{
  "success": false,
  "error": "Request blocked by policy",
  "block_reason": "SQL Injection pattern detected",
  "policy_info": {
    "policies_evaluated": 5,
    "blocked": true,
    "block_reason": "SQL Injection pattern detected",
    "processing_time_ms": 1,
    "matched_policies": [
      {
        "policy_id": "security-sqli-union",
        "policy_name": "SQL Injection - UNION",
        "category": "security-sqli",
        "severity": "critical",
        "action": "block"
      }
    ],
    "exfiltration_check": {
      "exceeded": false,
      "rows_returned": 0,
      "row_limit": 10000
    },
    "dynamic_policy_info": {
      "enabled": false,
      "evaluated": false
    }
  }
}

PolicyInfo Schema

The policy_info object provides detailed information about policy evaluation:

Field	Type	Description
policies_evaluated	integer	Number of policies evaluated
blocked	boolean	Whether request was blocked
block_reason	string	Reason for block (if blocked)
redactions_applied	integer	Number of field redactions
processing_time_ms	integer	Policy evaluation time in milliseconds
matched_policies	array	Policies that matched (see below)
exfiltration_check	object	Exfiltration limit check info (v3.2.0+)
dynamic_policy_info	object	Dynamic policy evaluation info (v3.2.0+)

matched_policies array items:

Field	Type	Description
policy_id	string	Unique policy identifier
policy_name	string	Human-readable policy name
category	string	Policy category (e.g., "pii-us", "security-sqli")
severity	string	Match severity (low, medium, high, critical)
action	string	Action taken (block, redact, warn, log)

exfiltration_check object (v3.2.0+):

Field	Type	Description
exceeded	boolean	Whether any limit was exceeded
limit_type	string	Type of limit exceeded (rows, bytes, none)
rows_returned	integer	Number of rows in response
row_limit	integer	Configured row limit (MCP_MAX_ROWS_PER_QUERY)
bytes_returned	integer	Response size in bytes
byte_limit	integer	Configured byte limit (MCP_MAX_BYTES_PER_QUERY)

dynamic_policy_info object (v3.2.0+):

Field	Type	Description
enabled	boolean	Whether dynamic policy evaluation is enabled
evaluated	boolean	Whether policies were actually evaluated
policies_checked	integer	Number of dynamic policies checked
policies_matched	integer	Number of policies that matched
blocked	boolean	Whether blocked by dynamic policy
block_reason	string	Reason for block (if blocked)
matched_policies	array	Details of matched dynamic policies
evaluation_time_ms	integer	Dynamic policy evaluation time
error	string	Error message (if evaluation failed)

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 all 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",
  "details": [
    {"name": "postgres-main", "status": "refreshed"},
    {"name": "redis-cache", "status": "refreshed"},
    {"name": "salesforce-crm", "status": "refreshed"}
  ]
}

POST /api/v1/connectors/refresh/{tenant_id}

Refresh connectors for a specific tenant.

Request:

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

Response (200 OK):

{
  "success": true,
  "tenant_id": "my-tenant",
  "refreshed_count": 2,
  "message": "Tenant connectors refreshed"
}

POST /api/v1/connectors/refresh/{tenant_id}/{connector_name}

Refresh a single connector for a tenant.

Request:

curl -X POST http://localhost:8080/api/v1/connectors/refresh/my-tenant/postgres-main

Response (200 OK):

{
  "success": true,
  "tenant_id": "my-tenant",
  "connector": "postgres-main",
  "status": "refreshed",
  "health": {
    "healthy": true,
    "latency_ms": 3.2
  }
}

GET /api/v1/connectors/cache/stats

Get connector cache statistics.

Request:

curl http://localhost:8080/api/v1/connectors/cache/stats

Response (200 OK):

{
  "cache_stats": {
    "total_entries": 15,
    "hit_rate": 0.94,
    "miss_rate": 0.06,
    "evictions": 3,
    "memory_bytes": 245760
  },
  "by_tenant": {
    "tenant-a": {"entries": 5, "hit_rate": 0.96},
    "tenant-b": {"entries": 4, "hit_rate": 0.92},
    "tenant-c": {"entries": 6, "hit_rate": 0.93}
  },
  "timestamp": "2025-01-02T10:30:00Z"
}

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"
}

Proxy Request Endpoint

POST /api/request

Execute a query through AxonFlow with policy enforcement and LLM routing.

Request:

curl -X POST http://localhost:8080/api/request \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: your-tenant" \
  -d '{
    "query": "Write a Python function to sort a list",
    "context": {
      "provider": "openai"
    }
  }'

Request Body:

Field	Type	Required	Description
query	string	Yes	The query/prompt to send to the LLM
context	object	No	Additional context including provider, model, etc.
context.provider	string	No	LLM provider to use (openai, anthropic, gemini)
context.model	string	No	Specific model to use

Response (200 OK):

{
  "success": true,
  "data": {
    "data": "Here is a Python function to sort a list...",
    "metadata": {
      "processed_at": "2025-12-28T12:30:00Z"
    }
  },
  "blocked": false,
  "policy_info": {
    "policies_evaluated": [],
    "static_checks": ["sql_injection", "pii_detection"],
    "processing_time": "1.234s",
    "tenant_id": "your-tenant",
    "code_artifact": {
      "is_code_output": true,
      "language": "python",
      "code_type": "function",
      "size_bytes": 245,
      "line_count": 12,
      "policies_checked": ["code-secrets", "code-unsafe", "code-compliance"],
      "secrets_detected": 0,
      "unsafe_patterns": 0
    }
  }
}

Response (Blocked):

{
  "success": false,
  "blocked": true,
  "block_reason": "Blocked by system policy: SQL Injection Prevention",
  "policy_info": {
    "policies_evaluated": ["sys_sqli_union"],
    "static_checks": ["sql_injection"],
    "processing_time": "0.5ms",
    "tenant_id": "your-tenant"
  }
}

Code Artifact Detection

When the LLM response contains code, the code_artifact field is included in policy_info:

Field	Type	Description
is_code_output	boolean	Whether the response contains code
language	string	Detected programming language
code_type	string	Code category (function, class, script, config, snippet)
size_bytes	integer	Total size of detected code
line_count	integer	Number of lines of code
policies_checked	array	Code governance policies evaluated
secrets_detected	integer	Count of potential secrets found
unsafe_patterns	integer	Count of unsafe code patterns

See Code Governance for details on code detection.

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(axonflow.AxonFlowConfig{
        Endpoint: "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!")
    }
}

Static Policy API

The Agent also provides a comprehensive Static Policy API for managing pattern-based enforcement rules. See Static Policy API for full documentation of:

• GET/POST /api/v1/static-policies - List and create policies
• GET/PUT/DELETE /api/v1/static-policies/{id} - Manage individual policies
• POST /api/v1/static-policies/test - Test patterns
• GET /api/v1/static-policies/effective - Get effective policies with overrides

Next Steps

• Static Policy API - Pattern-based policy management
• Orchestrator API Reference - Multi-agent execution
• LLM Provider API - LLM provider management
• Workflow API - Workflow execution and planning
• MCP Connectors - Data connector configuration
• SDK Documentation - Language-specific SDKs