Skip to main content

Orchestrator API Endpoints

The Orchestrator is AxonFlow's control-plane and request-processing service. It owns the governed process endpoint, audit search, export, and reporting, the decision feed and explainability endpoints, session overrides, multi-agent planning, policy templates, tenant policy CRUD, provider management, media governance config, connector marketplace state, and execution replay.

Most deployments expose this service internally on 8081 and let the Agent proxy requests to it. For internal admin tooling or platform automation, you can call it directly.

Base URL and Access Pattern​

http://localhost:8081

Recommended practice:

  • application traffic can come through the Agent proxy on 8080
  • internal platform automation can talk to the Orchestrator directly on 8081

Authentication and Context​

Application traffic authenticates at the Agent gateway (Basic auth), which then proxies to the Orchestrator and injects trusted identity headers derived from the authenticated client — any client-supplied values for these headers are overwritten at the gateway. Callers that talk to the Orchestrator directly (internal automation) must set the identity headers themselves.

HeaderWhere it matters
X-Tenant-IDRequired by the audit read/report/export, decisions, overrides, and session-summary handlers — a missing header returns 401 (or 400 on the override write paths). Set automatically by the Agent proxy from the authenticated credential.
X-Org-IDCustomer-organization scope; used by override writes and audit attribution
X-Client-IDSuccessor of X-Tenant-ID under the v9 identity model (emitted since platform v8.0.0); the Agent proxy emits both during the compatibility window
X-User-Email / X-User-IDCaller identity for override create/revoke and decision explainability
X-Axonflow-Proxy-AuthHMAC token the Agent proxy injects to prove the request came through the gateway; some write handlers (for example POST /api/v1/audit/tool-call) reject direct access without it in non-Community deployments

See the Auth And Header Matrix for the full picture.

Core Endpoint Families​

Governed request processing​

MethodPathPurpose
POST/api/v1/processGovern a request, evaluate policies, pick a provider, and return a response

The context object on /api/v1/process supports request-level provider controls such as provider and strict_provider.

Verified request fields on /api/v1/process:

FieldRequiredNotes
request_idNoGenerated if omitted
queryYesPrompt or governed request content
request_typeYesRequest classification used by policy and routing
userYesIncludes email, role, and tenant context
clientYesIncludes id and tenant context
contextNoProvider hints and other request metadata
mediaNoMultimodal inputs for media-governance flows (source, base64_data or url, mime_type per item)

Identity headers set by the Agent gateway take precedence over the JSON body: X-Tenant-ID overwrites the user/client tenant fields and X-Org-ID overwrites their org fields, so tenant and org attribution is always server-derived from auth, never client-supplied.

Verified response fields on /api/v1/process:

FieldMeaning
request_idRequest correlation ID
successWhether the request completed successfully
dataMain response payload
errorError string when processing fails
redactedWhether output redaction occurred
redacted_fieldsRedacted output fields
policy_infoPolicy evaluation result with allowed, applied_policies, risk_score, and routing overrides
provider_infoProvider, model, latency, token, and cost metadata
media_analysisPresent for multimodal requests when media analysis ran
processing_timeHuman-readable processing duration

Audit and compliance​

MethodPathPurpose
POST/api/v1/audit/searchSearch audit logs with filters
GET/api/v1/audit/{id}Full detail for a single audit record (v9.3.0+)
POST/api/v1/audit/exportBounded CSV/JSON export of filtered audit rows (v9.3.0+)
POST/api/v1/audit/reportPer-action counts, average latency, and top policies for a time range (v9.3.0+)
GET/api/v1/audit/session-summaryPer-session / per-day usage buckets (Enterprise; other builds return 501)
POST/api/v1/audit/summaryAggregate compliance summary for a time range
POST/api/v1/audit/tool-callRecord non-LLM tool calls
GET/api/v1/audit/tenant/{tenant_id}Retrieve tenant audit logs

The audit read endpoints force tenant scoping from the trusted X-Tenant-ID header and return 401 when it is missing; /api/v1/audit/tenant/{tenant_id} additionally returns 403 when the URL tenant does not match the session tenant. Audit entries carry plane, correlation_id, decision_id, and session_id fields for cross-plane correlation (empty strings on rows written before those columns existed).

POST /api/v1/audit/search accepts a JSON body with the filters user_email, client_id, action, session_id (v9.6.1+), decision_id, policy_name, override_id, start_time, end_time (RFC 3339), plus limit (default 100) and offset. user_email and client_id are partial matches (case-insensitive substring); session_id, decision_id, and override_id are exact; action takes a canonical verdict (allowed, blocked, redacted, needs_approval, error) and also matches legacy spellings stored on historical rows. The tenant is always forced from X-Tenant-ID — a tenant_id field in the body is ignored. Search start time is clamped to the tier's audit-retention window. The response is {"entries": [...], "total": <true total count>, "limit": ..., "offset": ...}.

Audit export​

POST /api/v1/audit/export?format=csv|json (default json) accepts the same filter body as search, including session_id, decision_id, policy_name, and override_id (filter parity shipped in v9.7.0), so an export always reconciles with the on-screen search for the same filters. Exports are capped at 50,000 rows, newest first; when the cap is hit the response carries X-Audit-Export-Truncated: true and X-Audit-Export-Row-Cap: 50000 headers. CSV columns: id, timestamp, user_email, tenant_id, org_id, policy_decision, request_type, query, response_sample, provider, model, response_time_ms, correlation_id, session_id (free-text cells are neutralized against spreadsheet formula injection). JSON exports return {"entries": [...], "count": ..., "truncated": ..., "row_cap": 50000}.

Audit report​

POST /api/v1/audit/report takes start_time and end_time (RFC 3339, range capped at 1 year) plus optional user_email and action filters, and returns {tenant_id, user_email?, start_time, end_time, total, by_action, avg_latency_ms, top_policies}. by_action always carries the full canonical verdict set (allowed / blocked / redacted / needs_approval / error), reporting 0 for verdicts with no rows.

Session summary​

GET /api/v1/audit/session-summary?start_date=...&end_date=...[&user_email=...][&limit=...] (Enterprise) aggregates audit activity into buckets keyed on session_id where present, falling back to one bucket per user per calendar day. The response is {tenant_id, user_email?, start_date, end_date, buckets[], bucket_limit, truncated}; each bucket carries session_id?/day?, user_email, tenant_id, start_time, end_time, total, by_action, tools[], tokens_used, cost, avg_latency_ms, and optional usage_metrics. Community builds mount the same route and return 501. Full request/response reference: Session Summary API.

Decisions and overrides​

The decision feed, explainability, and session-override endpoints are served by the Orchestrator (and proxied through the Agent on 8080):

MethodPathPurpose
GET/api/v1/decisionsTier-gated list of recent policy decisions
GET/api/v1/decisions/{id}/explainFull structured explanation for one decision
POST / GET/api/v1/overridesCreate / list session-scoped policy overrides
GET / DELETE/api/v1/overrides/{id}Fetch / revoke a single override

See the Decisions API and Overrides API for the full contracts.

Multi-agent planning​

MethodPathPurpose
POST/api/v1/planGenerate a plan
POST/api/v1/plan/executeExecute a stored plan
GET/api/v1/plan/{id}Get plan status
PUT/api/v1/plan/{id}Update a plan
POST/api/v1/plan/{id}/cancelCancel a plan
GET/api/v1/plan/{id}/versionsPlan version history
POST/api/v1/plan/{id}/resumeResume a plan when enabled by tier
POST/api/v1/plan/{id}/rollback/{version}Roll back a plan version when enabled by tier
GET/api/v1/plans/approvals/pendingList MAP steps pending human approval
POST/api/v1/plans/estimateEstimate the cost of a plan before executing it
GET/api/v1/plans/{id}/costCost breakdown for a stored plan

Governance and admin APIs​

Path familyPurpose
/api/v1/dynamic-policiesTenant policy CRUD, import/export, test, versions, effective view
/api/v1/policiesPolicy management CRUD, import/export, per-policy test and versions
/api/v1/templatesPolicy templates (list, categories, stats, apply)
/api/v1/llm-providersProvider management and routing
/api/v1/providers/status, /api/v1/providers/weightsProvider health status (GET) and routing weights (PUT)
/api/v1/connectorsConnector marketplace (list, details, install, uninstall, health)
/api/v1/media-governanceFeature status, config, and audit export
/api/v1/executionsExecution replay
/api/v1/unified/executionsUnified execution tracking across WCP and MAP
/api/v1/workflowsWorkflow Control Plane execution and HITL status
/api/v1/webhooksWebhook management
/api/v1/pricing, /api/v1/usagePricing metadata and usage summaries
/api/v1/budgetsBudget management and analytics (non-community)
/api/v1/policies/simulate, /api/v1/policies/impact-reportPolicy simulation and impact reporting (tier-gated)
/api/v1/evidenceCompliance evidence export (tier-gated)

Verified Example: POST /api/v1/process​

curl -X POST http://localhost:8081/api/v1/process \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "query": "Summarize the quarterly security report",
    "request_type": "chat",
    "user": {
      "email": "[email protected]",
      "role": "analyst",
      "tenant_id": "tenant-123"
    },
    "client": {
      "id": "security-app",
      "tenant_id": "tenant-123"
    },
    "context": {
      "provider": "openai",
      "strict_provider": false
    }
  }'

The response from process includes the request ID, success flag, response data, redaction state, policy information, provider information, and processing timing. That is the core surface most teams use when AxonFlow owns request routing end to end.

Example response shape:

{
  "request_id": "req_abc123",
  "success": true,
  "data": "Here is the governed summary.",
  "redacted": false,
  "redacted_fields": [],
  "policy_info": {
    "allowed": true,
    "applied_policies": ["tenant-cost-review"],
    "risk_score": 0.12,
    "required_actions": [],
    "processing_time_ms": 3
  },
  "provider_info": {
    "provider": "openai",
    "model": "gpt-4o",
    "response_time_ms": 842,
    "tokens_used": 598,
    "cost": 0.0049
  },
  "processing_time": "845ms"
}

Planning and MAP operations​

The planning routes are the public API surface behind AxonFlow's multi-agent planning features:

MethodPathPractical use
POST/api/v1/planGenerate and persist a plan for a complex task
POST/api/v1/plan/executeExecute a stored plan
GET/api/v1/plan/{id}Poll plan state from external tooling
PUT/api/v1/plan/{id}Adjust an in-progress or saved plan
POST/api/v1/plan/{id}/cancelCancel a plan
GET/api/v1/plan/{id}/versionsInspect plan history
POST/api/v1/plan/{id}/resumeResume a paused plan (tier-gated)
POST/api/v1/plan/{id}/rollback/{version}Roll back to a prior plan version (tier-gated)
POST/api/v1/plans/{id}/steps/{step_id}/approveApprove a MAP gated step
POST/api/v1/plans/{id}/steps/{step_id}/rejectReject a MAP gated step
GET/api/v1/plans/approvals/pendingPoll pending MAP step approvals

That matters for teams building sophisticated agent systems at scale: the same service that governs individual LLM calls is also where you automate plan lifecycle, step approval, replay, and audit.

Why This Matters Operationally​

  • Teams building advanced agent systems use the Orchestrator for planning, provider failover, audit search, replay, and policy automation.
  • Community users can start with core request processing and policy APIs, then move to evaluation or paid tiers when they need larger policy estates, richer replay, deeper governance, and more advanced operational control.
  • Platform teams often automate against this API surface for provider rollouts, policy changes, compliance reporting, and connector lifecycle workflows.

Operational Readiness Checklist​

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

Last updated on