Agent API Reference

The Agent is the first service most developers put in front of applications. It handles gateway-mode policy enforcement, MCP input and output checks, health and metrics endpoints, and proxy access to many Orchestrator api/v1 management APIs. If you are building a production AI gateway, the Agent is the surface your application and SDK integrations usually hit first.

Base URL and Role

Local development:

http://localhost:8080

The Agent does two different jobs:

• gateway mode endpoints such as /api/policy/pre-check and /api/audit/llm-call
• proxy mode access to control-plane endpoints like /api/v1/process, /api/v1/dynamic-policies, /api/v1/llm-providers, /api/v1/connectors, and /api/v1/executions

Authentication

All protected endpoints other than health and metrics require Basic auth:

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

Common headers:

Header	Use
Authorization	Basic auth for protected APIs
Tenant (from Basic auth)	Preferred tenant scope where required
X-Org-ID	Backward-compatible tenant scope on older handlers
Content-Type: application/json	POST and PUT requests

Core Agent Endpoints

Health and observability

Method	Path	Purpose
GET	/health	Liveness and readiness check
GET	/metrics	JSON metrics snapshot
GET	/prometheus	Prometheus scrape endpoint

Health response:

{
  "status": "healthy",
  "service": "axonflow-agent",
  "tier": "Evaluation",
  "timestamp": "2026-04-21T09:12:44Z",
  "version": "7.2.0",
  "capabilities": [
    {"name": "health_check", "since": "1.0.0", "description": "Basic health endpoint"},
    {"name": "proxy_llm_call", "since": "1.0.0", "description": "Proxy mode LLM calls with policy enforcement"}
  ],
  "sdk_compatibility": {
    "min_sdk_version":         {"python": "6.0.0", "typescript": "5.0.0", "go": "5.0.0", "java": "5.0.0"},
    "recommended_sdk_version": {"python": "6.4.0", "typescript": "5.4.0", "go": "5.4.0", "java": "5.4.0"}
  }
}

The tier field was added in platform v7.2.0 and reports the license tier the agent has loaded. Possible values:

• starting — license check has not completed yet; retry after a second
• community — no license loaded (community mode)
• Community, Evaluation, Professional, Enterprise, Plus — the validated license tier string (capitalized)

Operators can check the tier with a single curl:

curl -s http://localhost:8080/health | jq -r .tier

The capabilities array lists what the running platform supports. See Version Compatibility for how SDKs v3.8.0+ use it for runtime feature discovery.

Gateway mode

Method	Path	Purpose
POST	/api/policy/pre-check	Approve or block a request before your app calls an LLM directly
POST	/api/audit/llm-call	Record the LLM response after your app completes the call

Gateway mode is useful when you want AxonFlow governance, audit, cost tracking, and policy decisions, but your application keeps direct control over the provider call itself.

Pre-check response (approved):

{
  "approved": true,
  "context_id": "ctx_abc123",
  "requires_redaction": false,
  "policies": [],
  "approved_data": {
    "customer_profile": {
      "customer_id": "cust-123",
      "tier": "gold"
    }
  },
  "expires_at": "2026-03-29T12:05:00Z"
}

Pre-check response (blocked):

{
  "approved": false,
  "block_reason": "PII detected: US Social Security Number",
  "policies": ["sys_pii_ssn"],
  "expires_at": "2026-03-29T12:05:00Z"
}

Verified request fields for POST /api/policy/pre-check:

Field	Required	Notes
client_id	Yes	Must match the authenticated client in licensed modes
user_token	Yes	Used to resolve user context and tenant
query	Yes	Input query or prompt
data_sources	No	Optional approved MCP data sources
context	No	Additional policy context

Verified response fields from the handler:

Field	Meaning
context_id	Correlation ID for the later audit call
approved	Whether the request can proceed
requires_redaction	Whether downstream redaction is required
approved_data	Optional MCP data returned by approved sources
policies	Policies that matched or influenced the decision
rate_limit	Optional rate-limit status
budget_info	Optional budget decision details
expires_at	Expiry for the pre-check context
block_reason	Reason when the request is denied

Example:

curl -X POST http://localhost:8080/api/policy/pre-check \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "client_id": "client-id",
    "user_token": "user-123",
    "query": "Summarize the incident report",
    "context": {
      "department": "security",
      "workflow": "triage"
    }
  }'

For POST /api/audit/llm-call, the verified required fields are context_id, client_id, provider, model, token_usage, latency_ms, and response_summary.

Verified request body fields for POST /api/audit/llm-call:

Field	Required	Notes
context_id	Yes	Must come from the earlier pre-check
client_id	Yes	Must match the authenticated client in licensed modes
provider	Yes	Provider used for the external call
model	Yes	Model used for the external call
token_usage.prompt_tokens	Yes	Prompt/input tokens
token_usage.completion_tokens	Yes	Completion/output tokens
token_usage.total_tokens	Yes	Total token count
latency_ms	Yes	End-to-end provider latency
response_summary	Yes	Short response summary for audit storage
metadata	No	Optional arbitrary metadata

Successful responses return:

{
  "success": true,
  "audit_id": "aud_abc123"
}

Example:

curl -X POST http://localhost:8080/api/audit/llm-call \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "context_id": "ctx_abc123",
    "client_id": "client-id",
    "provider": "openai",
    "model": "gpt-4o",
    "token_usage": {
      "prompt_tokens": 412,
      "completion_tokens": 186,
      "total_tokens": 598
    },
    "latency_ms": 842,
    "response_summary": "Returned a concise incident summary for the analyst",
    "metadata": {
      "workflow": "incident-triage",
      "environment": "production"
    }
  }'

MCP policy enforcement

Method	Path	Purpose
POST	/api/v1/mcp/check-input	Evaluate an MCP query before connector execution
POST	/api/v1/mcp/check-output	Evaluate rows or payloads returned by a connector

These endpoints are what let you build governed database and SaaS integrations for AI agents. They are especially important when your application is exposing SQL, HTTP, Redis, MongoDB, or file-backed MCP connectors to higher-level agent frameworks.

Common MCP request fields:

Endpoint	Key request fields
/api/v1/mcp/check-input	client_id, user_token, tenant_id, connector_type, statement, optional operation, optional parameters
/api/v1/mcp/check-output	client_id, user_token, tenant_id, connector_type, optional response_data, optional message, optional metadata

Proxied control-plane APIs

The Agent also proxies many Orchestrator api/v1 families, including:

Path prefix	Common use
/api/v1/process	Governed request processing
/api/v1/dynamic-policies	Tenant policy CRUD
/api/v1/llm-providers	LLM provider management
/api/v1/templates	Policy template discovery and apply
/api/v1/connectors	Connector marketplace and install
/api/v1/executions	Replay and debugging
/api/v1/audit	Search, summary, and tool-call audit
/api/v1/rbi, /api/v1/sebi, /api/v1/masfeat, /api/v1/euaiact	Regulated-framework compliance modules (RBI FREE-AI, SEBI, MAS FEAT, EU AI Act). Agent proxies all four to the orchestrator so the compliance family is reachable through the single entry point.
/api/v1/policy-overrides	Canonical GET alias for the tenant override list. Matches the policy-categories / static-policies / dynamic-policies naming pattern. Available on platform v7.2.0+.

Available on v7.2.0

Both the /api/v1/euaiact/* proxy prefix and the /api/v1/policy-overrides GET alias shipped in platform v7.2.0. Older platforms return 404 page not found for these paths; use /api/v1/static-policies/overrides for the override list on pre-v7.2.0 agents.

What Senior Engineers Usually Do Here

• Platform teams terminate application traffic at the Agent and keep the Orchestrator on an internal network.
• AI application teams use gateway mode when they already own the provider call stack and just need AxonFlow governance, audit, and policy enforcement.
• Teams moving toward more centralized operations later adopt the broader Orchestrator APIs for provider routing, policy templates, replay, and connector lifecycle management.

That progression matters commercially too: community users can start with the Agent and solid governance basics, then move into evaluation or paid tiers when they need larger policy estates, richer control-plane automation, and stronger enterprise operations.

Related Docs

• Choosing a Mode
• Orchestrator Endpoints
• MCP Overview