API Reference
AxonFlow exposes two primary API surfaces:
- the Agent API on port
8080for gateway-mode policy checks, MCP input and output checks, health and metrics, and the proxy entrypoint most applications should call first - the Orchestrator API on port
8081for governed request processing, multi-agent planning, tenant policy management, provider management, execution replay, and other control-plane workflows
See working HTTP API examples with curl in the AxonFlow examples repository.
In self-hosted and production deployments, many api/v1 management endpoints are reachable through the Agent proxy as well as directly on the Orchestrator. For most application traffic, prefer the Agent because it is where request governance, gateway mode, MCP request checks, and authentication integration usually start. For internal platform operations, you may expose the Orchestrator directly on 8081 inside a trusted network.
Service Split
| Service | Local Port | Description |
|---|---|---|
| Agent | 8080 | Policy enforcement, gateway mode, MCP request checks, health, metrics, and proxied control-plane APIs |
| Orchestrator | 8081 | Request processing, audit search, planning, tenant policies, templates, provider routing, replay, and admin APIs |
Application traffic usually starts at http://localhost:8080. Platform and admin tooling can call http://localhost:8081 directly when you intentionally expose the Orchestrator in a trusted network.
Authentication and Tenant Context
All protected endpoints use HTTP Basic authentication. The server derives tenant and org context from the authenticated credentials — no separate tenant header is needed.
| Header | Required | Notes |
|---|---|---|
Authorization | Yes | Basic base64(clientId:clientSecret) — tenant is derived from the authenticated clientId |
X-User-ID | For mutating APIs | Used for create, update, apply, or per-tenant config changes (audit attribution) |
Content-Type | For POST/PUT | Usually application/json |
curl http://localhost:8080/api/v1/dynamic-policies \
-H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
For the cross-surface reference that includes portal sessions, SCIM, and admin APIs, use Auth And Header Matrix.
Public API Families
Gateway and request processing
| Reference | Description |
|---|---|
| Agent Endpoints | Gateway mode, MCP request checks, health, metrics, and proxied APIs |
| Orchestrator Endpoints | Direct request processing, planning, audit, connectors, and replay |
| Error Codes | What AxonFlow error payloads actually look like across handlers |
Governance and control plane
| Reference | Description |
|---|---|
| System Policy API | Pattern-based system policy CRUD on /api/v1/static-policies |
| Tenant Policy API | Condition-based tenant policy CRUD on /api/v1/dynamic-policies |
| Policy Templates API | Browse and apply reusable policy templates |
| LLM Provider API | Configure providers, routing weights, and health checks |
| Audit API | Search audit logs, summarize compliance activity, and record tool-call audit events |
Runtime operations and debugging
| Reference | Description |
|---|---|
| Connector Marketplace API | Discover, install, uninstall, and health-check MCP connectors |
| Cost Controls API | Community pricing and usage plus non-community budget management |
| Decision & Execution Replay API | List, inspect, export, and delete execution records |
| Media Governance Configuration API | Read media governance status and manage paid-tier per-tenant config |
Endpoint Index
Agent-first endpoints
| Method / Path | Purpose |
|---|---|
GET /health | Agent health check |
GET /metrics | JSON metrics snapshot |
GET /prometheus | Prometheus scrape endpoint |
POST /api/policy/pre-check | Gateway-mode approval before an external LLM call |
POST /api/audit/llm-call | Gateway-mode audit write after an external LLM call |
POST /api/v1/mcp/check-input | Policy-check an MCP query before execution |
POST /api/v1/mcp/check-output | Policy-check an MCP result after execution |
PathPrefix /api/v1/... | Proxy many orchestrator APIs such as policies, providers, templates, audit, connectors, budgets, and replay |
Core orchestrator endpoint families
| Method / Path | Purpose |
|---|---|
POST /api/v1/process | Governed request processing |
POST /api/v1/plan | Multi-agent planning |
POST /api/v1/plan/execute | Execute a stored plan |
GET /api/v1/plan/{id} | Get plan status |
POST /api/v1/audit/search | Search audit logs |
POST /api/v1/audit/tool-call | Record non-LLM tool calls |
POST /api/v1/audit/summary | Compliance summary |
| `GET | POST /api/v1/dynamic-policies` |
| `GET | POST /api/v1/llm-providers` |
GET /api/v1/executions | Replay and execution history |
How To Choose The Right Surface
- If your app is using gateway mode and makes the LLM call itself, start with Agent Endpoints.
- If your app wants AxonFlow to process and route the request, start with Orchestrator Endpoints.
- If your platform team is setting up governance, provider routing, templates, or replay, move into the dedicated control-plane references linked above.
- If you are validating production readiness, the public API docs show the community and evaluation path, while the protected docs add deeper enterprise operational workflows.
