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

Allowed responses return the minimal { allowed, policies_evaluated } shape. Block responses additionally carry explainability context that has been emitted since platform v7.1.0:

Field on a block	Type	Notes
decision_id	string (UUID)	Both endpoints. Pass to GET /api/v1/decisions/{decision_id}/explain for the full DecisionExplanation.
risk_level	enum	check-input only. low / medium / high / critical. Mirrors the highest matched policy's risk level.
policy_matches	array of ExplainPolicy	Both endpoints. Every policy that contributed to the block. Each element: policy_id, policy_name, action, risk_level, allow_override, policy_description.
override_available	boolean	check-input only. true when at least one matched policy has allow_override: true AND the caller is permitted to override. Absent on pre-v7.1.0 platforms.
override_existing_id	string	check-input only. Identifier of an active session override that is suppressing or modifying this decision.
redacted_message	string	check-output only. PII-masked text response. Mutually exclusive with redacted_data (rows): outputs populate at most one.

For JSON shapes and per-SDK reading patterns see MCP policy enforcement: explainability fields on a block.

Redaction fields on an allow (two-touch fulfillment)

When a POST /api/v1/decide verdict carries a redact_pii obligation, a PEP discharges it by calling the endpoint the obligation names and forwarding the engine-masked content (the two-touch model). These are the fields a PEP reads off the allow path of those endpoints — they are additive (omitempty), so callers that never enabled redaction see the byte-for-byte original shape.

check-input (request phase):

Field	Type	Notes
redaction_evaluated	boolean	Load-bearing fail-closed signal. true ⇒ the redaction detector actually ran (regardless of whether it masked anything); read redacted / redacted_statement. false or absent ⇒ the detector did not run (no detection config enabled) ⇒ a PEP fulfilling a redact_pii obligation MUST fail closed — do not forward the statement as if it were clean. This distinguishes "ran, found nothing" from "didn't run." Emitted on every evaluated allow path since platform v8.6.0.
redacted	boolean	true when the engine masked PII in the statement.
redacted_statement	string	The engine-masked request statement. Forward this — never re-derive it client-side. When redacted is true, an empty redacted_statement is a contradiction; fail closed.

check-output (response phase): there is no redaction_evaluated field on this endpoint — /decide is pre-call and only emits request-phase obligations, so response fulfillment is driven entirely by the PEP's call to check-output. Read the engine-masked response from redacted_data (rows) or redacted_message (string; mutually exclusive — at most one is populated). A response-leg PEP fails closed on any of: non-2xx status, allowed: false, engine unreachable/timeout, or a redacted_data of an unexpected (non-string, when a string was expected) shape — it must never forward the raw backend response when the engine round-trip did not cleanly succeed.

See Building a Policy Enforcement Point for the complete decide → fulfill → forward loop and every fail-closed rule.

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

Operational Readiness Checklist

Before relying on this page in a production rollout, pair it with the core operations docs:

• Deployment Mode Matrix for self-hosted, Evaluation, Enterprise, SaaS, and In-VPC fit
• Failure Modes And Recovery for degraded-provider, connector, approval, and runtime behavior
• Capacity Planning for sizing and growth signals
• Community vs Evaluation vs Enterprise for limits, support surfaces, and upgrade triggers