Orchestrator API Endpoints

The Orchestrator is AxonFlow's control-plane and request-processing service. It owns the governed process endpoint, audit search and summary, 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

Most protected routes use Basic auth plus tenant context headers where the handler requires them.

Header	Where it matters
Authorization	Most protected routes
Tenant (from Basic auth)	Tenant-scoped policies, templates, replay, audit summary, media governance
X-Org-ID	Backward-compatible tenant scope on older orchestrator handlers
X-User-ID	Create, update, apply, or per-tenant config operations

Core Endpoint Families

Governed request processing

Method	Path	Purpose
POST	/api/v1/process	Govern 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:

Field	Required	Notes
request_id	No	Generated if omitted
query	Yes	Prompt or governed request content
request_type	Yes	Request classification used by policy and routing
user	Yes	Includes email, role, and tenant context
client	Yes	Includes id and tenant context
context	No	Provider hints and other request metadata
media	No	Multimodal inputs for media-governance flows

Verified response fields on /api/v1/process:

Field	Meaning
request_id	Request correlation ID
success	Whether the request completed successfully
data	Main response payload
error	Error string when processing fails
redacted	Whether output redaction occurred
redacted_fields	Redacted output fields
policy_info	Policy evaluation result with allowed, applied_policies, risk_score, and routing overrides
provider_info	Provider, model, latency, token, and cost metadata
media_analysis	Present for multimodal requests when media analysis ran
processing_time	Human-readable processing duration

Audit and compliance

Method	Path	Purpose
POST	/api/v1/audit/search	Search audit logs
POST	/api/v1/audit/tool-call	Record non-LLM tool calls
GET	/api/v1/audit/tenant/{tenant_id}	Retrieve tenant audit logs
POST	/api/v1/audit/summary	Aggregate compliance summary for a time range

Multi-agent planning

Method	Path	Purpose
POST	/api/v1/plan	Generate a plan
POST	/api/v1/plan/execute	Execute a stored plan
GET	/api/v1/plan/{id}	Get plan status
PUT	/api/v1/plan/{id}	Update a plan
POST	/api/v1/plan/{id}/cancel	Cancel a plan
GET	/api/v1/plan/{id}/versions	Plan version history
POST	/api/v1/plan/{id}/resume	Resume a plan when enabled by tier
POST	/api/v1/plan/{id}/rollback/{version}	Roll back a plan version when enabled by tier

Governance and admin APIs

Path family	Purpose
/api/v1/dynamic-policies	Tenant policy CRUD
/api/v1/templates	Policy templates
/api/v1/llm-providers	Provider management and routing
/api/v1/connectors	Connector marketplace
/api/v1/media-governance	Feature status and config
/api/v1/executions	Execution replay
/api/v1/budgets	Non-community budget management

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:

Method	Path	Practical use
POST	/api/v1/plan	Generate and persist a plan for a complex task
POST	/api/v1/plan/execute	Execute 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}/cancel	Cancel a plan
GET	/api/v1/plan/{id}/versions	Inspect plan history
POST	/api/v1/plans/{id}/steps/{step_id}/approve	Approve a WCP/MAP gated step
POST	/api/v1/plans/{id}/steps/{step_id}/reject	Reject a WCP/MAP gated step

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.

Related Docs

• Workflow API
• Decision & Execution Replay API
• LLM Provider API