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.

Generated API reference

The full endpoint-by-endpoint reference for the Agent — every request field, response field, and status code — is rendered from the published OpenAPI spec at the Agent API reference. This page is the guide: it explains when to use each surface and the rules a well-behaved client must implement, and links into the generated reference instead of duplicating schema tables.

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	Generated reference
GET	/health	Liveness and readiness check	healthCheck
GET	/metrics	JSON metrics snapshot	getMetrics
GET	/prometheus	Prometheus scrape endpoint	getPrometheusMetrics

The tier field in the /health response 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	Generated reference
POST	/api/policy/pre-check	Approve or block a request before your app calls an LLM directly	gatewayPreCheck
POST	/api/audit/llm-call	Record the LLM response after your app completes the call	auditLLMCall

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.

The full request and response schemas — including requires_redaction, approved_data, rate-limit and budget details, and the blocked shape with block_reason — are in the generated reference linked above. The rules a gateway-mode client must implement:

• On an approved pre-check, persist context_id — the follow-up POST /api/audit/llm-call requires it, and pre-check contexts expire (expires_at).
• On a blocked pre-check (approved: false), do not call the provider. Surface block_reason and the matched policies to the caller.

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 context_id must come from the earlier pre-check and must not have expired. The required fields and success shape are documented at auditLLMCall.

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	Generated reference
POST	/api/v1/mcp/check-input	Evaluate an MCP query before connector execution	mcpCheckInput
POST	/api/v1/mcp/check-output	Evaluate rows or payloads returned by a connector	mcpCheckOutput

The generated reference documents this family under the /mcp/ path prefix (/mcp/check-input, /mcp/check-output); the same operations back the /api/v1/mcp/ spellings shown here. Full request schemas (client_id, user_token, tenant_id, connector_type, statement, and the rest) are in the linked reference.

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.

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.

Other Agent surfaces

The generated Agent API reference also covers surfaces this guide does not repeat: Decision Mode (decide), the OpenAI-compatible gateway (chatCompletionsOpenAICompat), MCP connectors, query, and tool execution (listMCPConnectors, mcpQuery, mcpExecute), connector cache refresh (refreshAllConnectors), the static-policy family (listStaticPolicies), HITL and circuit breaker, EU AI Act accuracy and conformity, and audit-trail verification (verifyAuditChain, verifyAuditRecord, getAuditSigningKey).

Proxied control-plane APIs

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

Path prefix	Common use	Generated reference
/api/v1/process	Governed request processing	processRequest
/api/v1/dynamic-policies	Tenant policy CRUD	Documented as the policies family: listPolicies, listDynamicPolicies
/api/v1/llm-providers	LLM provider management	listLLMProviders
/api/v1/templates	Policy template discovery and apply	Not yet in the published OpenAPI specs
/api/v1/connectors	Connector marketplace and install	listConnectors
/api/v1/executions	Replay and debugging	listExecutions
/api/v1/audit	Search, summary, and tool-call audit	searchAuditLogs
/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.	getRBIDashboard, getSEBIDashboard, createEUAIActExport; MAS FEAT is not yet in the published OpenAPI specs
/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+.	Documented on the Agent surface as listStaticPolicyOverrides (/api/v1/static-policies/overrides); the /api/v1/policy-overrides alias itself is not yet in the published OpenAPI specs

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