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
X-Axonflow-Client	Optional <client>/<version> identification (e.g. mcp-proxy/0.3.1, claude-code-plugin/1.9.1). Telemetry and origin classification only — never part of authentication; malformed values are silently ignored. See Auth And Header Matrix.
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.

OTLP telemetry ingest (Enterprise)

Method	Path	Purpose
POST	/v1/logs	OTLP/HTTP log ingest (Claude Code / Cowork OpenTelemetry exports land as canonical audit records)
POST	/v1/metrics	OTLP/HTTP metric ingest

Both routes accept standard OTLP/HTTP payloads (application/x-protobuf or application/json) and are authenticated — org and tenant attribution comes from the authenticated credentials, never from the (spoofable) OTLP resource attributes. On Community builds the routes are mounted but return 501 Not Implemented; the ingest plane is an Enterprise feature.

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 tool, optional parameters, optional content_type
/api/v1/mcp/check-output	client_id, user_token, tenant_id, connector_type, optional response_data, optional message, optional metadata

On check-input, connector_type names the server the tool lives on, and the optional tool field (v9.10.0+) names the specific tool being invoked on it. The two are the request-plane mirror of the Decision API's target.server / target.tool and are recorded on the decision audit row as policy_details.tool_server and policy_details.tool_name. Sending both lets policies scope to a single tool on a server rather than the whole connector; when tool is omitted, only the server axis is recorded. (Pre-v9.10.0 platforms ignore an unknown tool field rather than failing — but do not rely on tool-level scoping until you are on v9.10.0 or later.)

On check-input, the optional content_type field selects the request-redaction detector; empty defaults to text/plain. A content_type with no registered detector is rejected fail-closed with HTTP 415 and the flat error body {"success": false, "error": "no redaction detector registered for content_type: ...", "blocked": false} — the engine refuses to pass through content it cannot govern, so the caller must not forward it either.

Allowed responses return { allowed, policies_evaluated, decision_id } plus optional policy_info and the redaction fields described below — every governance decision (allow and block) mints a decision_id. 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	check-input only. Every policy that contributed to the block. Each element: policy_id, policy_name, risk_level, allow_override, optional policy_version.
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.

check-output block responses carry allowed: false, block_reason, decision_id, policies_evaluated (always serialized, but 0 on block responses — the count is only populated on the allow path), and — on an exfiltration-limit block — exfiltration_info. There is no redacted_message field on check-output: when a string output is masked on the allow path, the masked text is returned in redacted_data (see below).

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):

Field	Type	Notes
redaction_evaluated	boolean	Same load-bearing fail-closed signal as on check-input, emitted on this endpoint since platform v9.7.0: true ⇒ the response-redaction pipeline actually ran (regardless of whether it masked anything). false or absent (including on any pre-v9.7.0 platform, which never emits it here) ⇒ the redactor did not run ⇒ a PEP fulfilling a response-phase redact_pii obligation MUST fail closed — the absence of redacted_data cannot be trusted as "nothing to mask."
redacted_data	rows or string	The engine-masked response. For row-style results (response_data) it holds the redacted rows; for string outputs (message) it holds the masked string. Present only when something was masked. Forward only the engine-returned content.

/decide is pre-call and only emits request-phase obligations, so response fulfillment is driven entirely by the PEP's call to check-output. Independent of redaction_evaluated, 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