AxonFlow Agent API (2.1.0)

Returns service health status. During startup, returns status: starting. Once fully initialized, returns status: healthy.

This endpoint responds immediately even during initialization, allowing ECS/ALB health checks to pass while the service starts up.

Main entry point for Proxy Mode. The Agent:

1. Validates client license key
2. Validates user JWT token
3. Verifies tenant isolation
4. Evaluates static policies (PII detection, etc.)
5. Forwards to Orchestrator if allowed
6. Returns response with policy metadata

Use this endpoint when you want AxonFlow to intercept and process all LLM requests.

Test how policies would evaluate a query without making an actual request. Useful for debugging and policy development.

Returns all registered client applications

Register a new client application

Gateway Mode Step 1: Call this endpoint before making your own LLM API call.

The Agent validates the request against policies and returns:

• approved: true if the request is allowed
• context_id to link with the subsequent audit call
• Optional approved_data from MCP connectors
• Rate limit information

approved_data is only prefetched for clean approvals (#2868): when the request is blocked, requires HITL approval, or requires redaction, connector prefetch is skipped and approved_data is never populated — governed data is not fetched for a request that may not proceed.

Context expires after 5 minutes.

Example Flow

1. SDK calls pre-check → gets context_id, approved=true
2. SDK makes direct LLM call (OpenAI, Anthropic, etc.)
3. SDK calls audit with context_id and response metadata

Gateway Mode Step 2: Call this endpoint after your LLM API call completes.

Records:

• Token usage for billing and quotas
• Latency metrics
• Provider and model information
• Estimated cost

Requires a valid context_id from pre-check (not expired).

Decision Mode endpoint (ADR-056 / epic #2426). The customer's infrastructure gateway (Policy Enforcement Point) calls this endpoint per request to get a verdict (allow / deny / needs_approval) and enforces the result. AxonFlow is consulted, never on the traffic path.

The shared-policy engine behind this endpoint is the same engine that backs Gateway Mode's POST /api/policy/pre-check. The difference is the caller: Gateway Mode is called by application code; Decision Mode is called by an infrastructure gateway.

M1 scope: static policies only (PII detection, SQL injection, dangerous patterns, RBI India PII, compliance categories) to keep the inline RPC budget in single-digit milliseconds. Dynamic/custom policy support is M2 scope per the epic.

OTel trace correlation: the response carries a W3C-compatible 32-hex trace_id. When the caller passes a traceparent header, its trace-id is reused so multi-gateway-layer decisions stitch into one end-to-end trace. Each decision also emits an OpenTelemetry span on the axonflow.agent.decision tracer.

Available at all tiers (Community through Enterprise) — the policy engine is the same one Gateway Mode uses.

Returns the MCP connectors the authenticated tenant may reach, with their health status. Deployment-shared connectors (those registered under the wildcard tenancy *) are included for every tenant; another tenant's connectors are not (platform/agent/mcp_handler.go:612-620).

Connectors provide access to external data sources:

• PostgreSQL
• Cassandra
• Salesforce
• Snowflake
• Amadeus (travel API)
• Slack

Authentication. Wrapped in apiAuthMiddleware (platform/agent/mcp_handler.go:581); the tenancy comes from the credential, never from a caller-supplied header or path segment. Registered for GET only — apiAuthMiddleware forwards CORS preflights unauthenticated, so registering OPTIONS would reach the handler with no identity in context.

(Behaviour change in #3067: this route was previously registered with no auth middleware and returned every tenant's connector names, types, versions, capabilities, health and raw driver error strings to an anonymous caller.)

Returns health status for one of the authenticated tenant's connectors (or a deployment-shared one).

Naming another tenant's connector returns the same 404 as a nonexistent one — there is no existence oracle, and no live connection is opened with the other tenant's credentials (platform/agent/mcp_handler.go:665-676).

Authentication. Wrapped in apiAuthMiddleware (platform/agent/mcp_handler.go:584), GET only.

(Behaviour change in #3067: this route was previously registered with no auth middleware, so an anonymous caller could name any tenant's connector and have the agent open a live connection with that tenant's decrypted credentials.)

Execute a read-only query via an MCP connector.

This follows the MCP Resource pattern for data retrieval. For write operations, use /mcp/tools/execute.

Audit Logging

All MCP queries are automatically logged to the mcp_query_audits table with:

• Request phase: SQLi detection results, PII blocking decisions
• Response phase: PII redaction details, redacted field paths
• Exfiltration checks: Row counts, volume limit violations
• Result: Success/failure, error messages, duration

Each audit entry includes audit_id for correlation with SDK PolicyInfo. Statement content is stored as SHA256 hash for privacy.

Execute a write command via an MCP connector.

This follows the MCP Tool pattern for data modification. For read operations, use /mcp/resources/query.

Audit Logging

All MCP execute operations are automatically logged to the mcp_query_audits table with:

• Request phase: SQLi detection results, dangerous operation blocking
• Result: Rows affected, success/failure, error messages, duration

Each audit entry includes audit_id for correlation. Operation type (INSERT, UPDATE, DELETE) is stored in the operation field.

Validate an MCP request (query or command) against configured policies without executing it.

This endpoint enables external orchestrators (LangGraph, CrewAI, custom pipelines) to use AxonFlow as a policy gate while managing MCP connector execution themselves.

Policy Evaluation

The following policies are evaluated in order:

1. Dynamic policies (if enabled): Rate limits, budgets, time-access, role-access via Orchestrator
2. Static policies: SQL injection detection, dangerous query blocking, PII detection

If any policy blocks the request, the response returns allowed: false with a block_reason.

When to Use

Use check-input + check-output when your orchestrator manages MCP execution natively. Use /mcp/resources/query or /mcp/tools/execute when you want AxonFlow to handle both policy enforcement and connector execution.

Audit Logging

All check-input evaluations are logged to the mcp_query_audits table with operation: "check-input" for compliance tracking. Audit entries include parameters_hash (SHA-256) and parameter_count for forensic analysis.

Validate MCP response data against configured policies without having executed the query through AxonFlow.

This endpoint enables external orchestrators to apply AxonFlow's output-side policy enforcement (PII redaction, exfiltration limits, SQLi response scanning) to data they fetched from MCP connectors independently.

Policy Evaluation

The following checks are applied in order:

1. SQLi response scanning: Detects SQL injection artifacts in response data
2. Static response policies: PII detection and redaction (SSN, credit card, Aadhaar, etc.)
3. Exfiltration limits (query-style only): Row count and byte size limits

If PII is detected, the response includes redacted_data with masked values. If exfiltration limits are exceeded, the response returns allowed: false.

Query vs Execute Responses

• Query responses (response_data): Full policy evaluation including exfiltration checks
• Execute responses (message): SQLi scanning and PII checks only (no exfiltration limits)

Audit Logging

All check-output evaluations are logged to the mcp_query_audits table with operation: "check-output" for compliance tracking.

Unauthenticated liveness probe.

⚠️ healthy_count + unhealthy_count do not sum to total_connectors, by design (platform/agent/mcp_handler.go:3377-3405). Because this route is anonymous, the live health checks it performs are limited to the deployment-shared (operator-configured, wildcard-tenancy *) connectors, while total_connectors keeps its pre-existing deployment-wide meaning so operator dashboards do not silently change scale. A deployment consisting only of tenant-owned connectors therefore reports healthy: true with zero counts even if every backend is down.

Use the authenticated GET /mcp/connectors for per-tenant connector health.

(Behaviour change in #3067: this route previously opened a live connection to every tenant's backend on every anonymous GET — cross-tenant credential use plus a free amplification lever.)

Invalidates and refreshes cached connector instances. Use this after configuration changes or deployments.

The scope depends on which credential you present (platform/agent/connector_refresh_api.go:184-216):

Performance impact: the next request for each evicted connector incurs factory-creation overhead.

Authentication. This route is wrapped in apiAuthMiddleware (platform/agent/connector_refresh_api.go:123) and the tenancy comes from the authenticated identity — a caller can no longer evict another tenant's pool. Supply either:

• Authorization: Basic base64(clientId:clientSecret) — the tenant lane (no credentials are required when DEPLOYMENT_MODE=community); or
• X-Internal-Service-ID + X-Internal-Service-Token — the operator lane, which is the only way to trigger a deployment-wide eviction.

(Historical note: these four routes were registered with no auth middleware at all — #2883. They are authenticated as of #3067; the pre-#3067 "deploy behind network-level controls" advisory no longer applies.)

stats.cached_connectors is structurally 0 on this route: the refresh empties the scope immediately before the count is taken. That is the success signal, not a failure.

Invalidates and refreshes all cached connector instances for a tenant. Use this after updating a tenant's connector configuration.

{tenant_id} is not a selector. It is validated against the identity apiAuthMiddleware resolved and a mismatch is 403 (platform/agent/connector_refresh_api.go:152-156); the tenancy that is actually refreshed always comes from the credential.

• Basic auth: the resolved identity is your licensed org, so this route can only ever refresh your own pool.
• Internal-service credential: the resolved identity is whatever X-Tenant-ID you send (platform/agent/authenticator.go:127-130), so an operator targets a named tenant by sending that header and the matching path segment. Naming a tenant in the path with no X-Tenant-ID is 403, because the identity then falls back to the synthetic orchestrator-internal client id.

stats.cached_connectors is structurally 0 on this route — the refresh empties the tenant's scope immediately before the count is taken.

Invalidates and refreshes a specific connector instance for a tenant. Use this after updating a single connector's credentials or configuration.

{tenant_id} is not a selector — same contract as POST /api/v1/connectors/refresh/{tenant_id}: the segment is validated against the authenticated identity and a mismatch is 403 (platform/agent/connector_refresh_api.go:152-156).

Unlike the two broader refresh routes, stats.cached_connectors here is informative: it is the caller's remaining cached-connector count after this one connector was evicted (platform/agent/connector_refresh_api.go:314,404-408).

Returns the caller's cached-connector count. The response is tenant-scoped (platform/agent/connector_refresh_api.go:350-355): cached_connectors is the authenticated tenant's own count, not the deployment's.

The cache-health counters are operator telemetry. hits, misses, evictions, factory_creations, factory_failures, connection_errors, hit_rate_percent, last_eviction and last_factory_create are deployment-wide figures. They appear here only inside a deployment object, and only for the internal-service credential (platform/agent/connector_refresh_api.go:356-369). A tenant caller must not read their absence as zero — it has no cache-health data on this surface.

Un-scoped equivalents for five of them are always available to operators on /prometheus as axonflow_connector_cache_stats{stat="cached_connectors"|"hits"|"misses"|"evictions"|"hit_rate"}, refreshed on every call to this endpoint (platform/agent/connector_refresh_api.go:338-342). factory_creations, factory_failures, connection_errors, last_eviction and last_factory_create have no Prometheus series — the deployment block is their only surface.

Authentication. Wrapped in apiAuthMiddleware (platform/agent/connector_refresh_api.go:132). This route takes no {tenant_id} path segment, so it never returns 403.

(Historical note: this route was registered with no auth middleware at all and served the deployment-wide counters to anonymous callers — #2883, where the evictions delta was an existence oracle for (tenant, connector) pairs. Authenticated and scoped as of #3067.)

Returns real-time performance metrics including:

• Request counts (total, success, failed, blocked)
• Latency percentiles (P50, P95, P99)
• Per-stage timing (auth, policy, network)
• Request type breakdown
• Connector metrics

Returns metrics in Prometheus exposition format for scraping

Route a high-risk AI decision for human review. EU AI Act Article 14 requires human oversight for high-risk AI systems.

Requires both X-Org-ID and X-Tenant-ID headers (stamped by the auth middleware) — 400 when either is missing.

Enterprise only — community builds expose only GET /api/v1/hitl/status.

Retrieve approval requests, filtered and paginated. Tenant scoping comes from the authenticated request context (RLS), not a query parameter.

Approve a pending request to allow AI execution

Reject a pending request to block AI execution

Record an authorized override of a pending request — the caller takes responsibility for letting the action proceed outside the normal approve/reject flow. Requires a justification for the audit trail.