API Reference

AxonFlow exposes two main APIs for interacting with the platform.

Community Examples

See working HTTP API examples with curl in the AxonFlow examples repository.

Services

Service	Local Port	Description
Agent	8080	Policy enforcement, LLM routing, MCP connectors
Orchestrator	8081	Multi-agent planning, workflow coordination

API Documentation

Core APIs

Reference	Description
Agent Endpoints	Policy enforcement, LLM proxy, MCP connectors
Orchestrator Endpoints	Multi-agent planning and parallel execution
Error Codes	Standard error codes and troubleshooting

Management APIs

Reference	Description
LLM Provider API	Configure LLM providers and routing
Static Policy API	Manage pattern-based enforcement policies
Dynamic Policy API	Manage Rego-based runtime policies
Policy Templates API	Browse and apply policy templates
Workflow API	Execute workflows and multi-agent planning
Decision & Execution Replay API	Query, debug, and export execution history with policy decisions
Audit API	Search and retrieve audit logs
Cost Controls API	Budget management and usage tracking
Connector Marketplace API	Discover, install, and manage connectors

Authentication

All API requests require Basic authentication using your client ID and client secret:

curl http://localhost:8080/api/v1/static-policies \
  -H "Authorization: Basic $(echo -n 'your-client-id:your-client-secret' | base64)"

Header	Required	Description
Authorization	Yes	Basic auth with clientId:clientSecret base64-encoded
X-Org-ID	No	Tenant identifier for multi-tenant isolation
X-User-ID	No	User identifier for audit trail
Content-Type	For POST/PUT	application/json

Endpoint Index

Agent Endpoints (port 8080)

Category	Base Path	Description
Health & Metrics	/health, /metrics, /prometheus	Service health, JSON metrics, Prometheus scraping
Policy Enforcement	/api/policy/pre-check	Pre-execution policy evaluation
Policy Test	/api/policies/test	Test queries against policies (no audit)
Audit Recording	/api/audit/llm-call	Record LLM interactions for compliance
Proxy Request	/api/request	Full LLM request with policy enforcement
Static Policies	/api/v1/static-policies	CRUD for pattern-based enforcement rules
LLM Providers	/api/v1/llm-providers	Provider configuration and routing
MCP Connectors	/mcp/connectors, /mcp/resources/query	Connector management and query execution
Client Management	/api/clients	API client registration
Connector Refresh	/api/v1/connectors/refresh	Reload connector configurations

Orchestrator Endpoints (port 8081)

Category	Base Path	Description
Health	/health	Service health check
Dynamic Policies	/api/v1/dynamic-policies	CRUD for condition-based runtime policies
Policy Templates	/api/v1/templates	Browse and apply policy templates
Workflows	/api/v1/workflows/execute	Workflow execution and tracking
Multi-Agent Planning	/api/v1/plan	LLM-powered task decomposition
Audit Search	/api/v1/audit/search	Search and retrieve audit logs
Budgets	/api/v1/budgets	Budget management and usage tracking
Usage	/api/v1/usage	LLM usage summaries and breakdowns
Connectors	/api/v1/connectors	Connector marketplace discovery and install
Executions	/api/v1/workflows/executions	Query workflow execution history

Rate Limiting

API requests are subject to rate limiting. When rate-limited, the API returns HTTP 429 Too Many Requests. Default limits depend on the deployment tier. Use the Retry-After header value to determine when to retry.

Common Endpoints

Health Checks

# Agent health
curl http://localhost:8080/health

# Orchestrator health
curl http://localhost:8081/health

Policy Pre-Check (Agent)

The primary policy enforcement endpoint for Gateway Mode:

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

Dynamic Policies (Orchestrator)

# List policies
curl http://localhost:8081/api/v1/dynamic-policies \
  -H "Authorization: Basic $(echo -n 'my-app:my-secret' | base64)" \
  -H "X-Org-ID: my-tenant"

# Create a policy
curl -X POST http://localhost:8081/api/v1/dynamic-policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'my-app:my-secret' | base64)" \
  -H "X-Org-ID: my-tenant" \
  -d '{
    "name": "block-pii",
    "type": "content",
    "priority": 100,
    "enabled": true
  }'

Response Format

The /api/v1/process endpoint returns the OrchestratorResponse format:

{
  "request_id": "req_abc123",
  "success": true,
  "data": "The weather in Paris is currently 15°C.",
  "redacted": false,
  "redacted_fields": [],
  "policy_info": {
    "allowed": true,
    "applied_policies": ["governance.rate_limit"],
    "risk_score": 0.1,
    "processing_time_ms": 2
  },
  "provider_info": {
    "provider": "openai",
    "model": "gpt-4o",
    "response_time_ms": 856,
    "tokens_used": 43
  },
  "processing_time": "860ms"
}

Other API endpoints return resource-specific JSON. See individual endpoint docs for response formats.

Error Responses

All API endpoints return errors in a consistent JSON format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Common HTTP Status Codes:

HTTP Status	Description
400	Bad Request -- Invalid JSON or missing required fields
401	Unauthorized -- Missing or invalid authentication
403	Forbidden -- Insufficient permissions or policy blocked
404	Not Found -- Resource does not exist
409	Conflict -- Resource already exists
429	Too Many Requests -- Rate limit exceeded
500	Internal Server Error

Example (policy blocked):

{
  "error": {
    "code": "POLICY_VIOLATION",
    "message": "Request blocked by policy: pii-detection"
  }
}

See Error Codes for the complete list.

Next Steps

• Review Agent Endpoints for policy enforcement
• Review Orchestrator Endpoints for multi-agent workflows
• See Error Codes for troubleshooting