API Reference

This page covers the public orchestration-facing APIs that engineers use when they want AxonFlow to either:

• generate and run multi-agent plans
• govern external workflows through the Workflow Control Plane (WCP)
• inspect execution history and approval state

The orchestration surface spans both the Agent and the Orchestrator, but the public orchestration APIs should normally be reached through the Agent on 8080. That keeps request authentication, tenant context, and governance enforcement consistent.

Base URLs

http://localhost:8080  # Agent
http://localhost:8081  # Orchestrator

Recommended access pattern:

• use the Agent for MAP, WCP, SDK integrations, UI access, and unified execution reads
• keep direct Orchestrator exposure limited to tightly controlled internal operations that are not part of the public application flow

Starting with v6.0.0, the Agent also proxies enterprise endpoints that were previously only available on the Orchestrator. These include policy simulation, evidence export, RBI/SEBI compliance, HITL approval management, webhook management, and media governance. Routing all traffic through the Agent on port 8080 keeps authentication, tenant resolution, and audit logging consistent.

MAP API: Generate, Then Execute

The current MAP implementation is a two-step lifecycle, not a single plan-and-execute call:

1. POST /api/v1/plan generates and stores a plan
2. POST /api/v1/plan/execute executes a stored plan

That distinction matters for production systems because it lets teams inspect, update, cancel, resume, version, or roll back a plan before and during execution.

Verified MAP routes

Method	Path	Purpose
POST	/api/v1/plan	Generate and store 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	View plan history
POST	/api/v1/plan/{id}/resume	Resume a paused plan when enabled by tier
POST	/api/v1/plan/{id}/rollback/{version}	Roll back a version when enabled by tier
POST	/api/v1/plans/{id}/steps/{step_id}/approve	Approve a gated MAP step
POST	/api/v1/plans/{id}/steps/{step_id}/reject	Reject a gated MAP step
POST	/api/v1/plans/estimate	Estimate plan cost
GET	/api/v1/plans/{id}/cost	Read plan cost

Generate a plan

curl -X POST http://localhost:8080/api/v1/plan \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "query": "Research remote work benefits for software teams",
    "domain": "generic",
    "execution_mode": "auto",
    "user": {
      "id": 123,
      "email": "[email protected]",
      "role": "analyst",
      "tenant_id": "tenant-123"
    },
    "client": {
      "id": "research-app",
      "name": "research-app",
      "tenant_id": "tenant-123"
    }
  }'

Verified request fields:

Field	Required	Notes
query	Yes	Task to plan
domain	No	Defaults to generic if omitted
execution_mode	No	Defaults to auto if omitted
user	Yes	Required for authenticated planning
client	No in JSON shape, but used by governance and audit flows	Tenant and app context
context	No	Additional planning metadata

The response is a PlanResponse that includes:

Field	Meaning
success	Whether generation succeeded
plan_id	Stored plan identifier
status	Plan lifecycle status (e.g., pending, in_progress, completed, failed)
steps	Generated plan steps
workflow_execution_id	Execution-tracking identifier when applicable
result	Optional result payload
metadata	Task and timing metadata
policy_info	Governance result when available
error	Error message when generation fails

Execute a stored plan

POST /api/v1/plan/execute is the step that actually runs a previously generated plan. Route MAP requests through the Agent rather than calling the Orchestrator directly, because plan generation expects authenticated user and client context for governance compliance.

WCP API: Govern External Workflows

The Workflow Control Plane adds governance to external orchestrators like LangGraph, LangChain, CrewAI, and custom workflow runners.

Verified workflow lifecycle routes

Method	Path	Purpose
POST	/api/v1/workflows	Register a workflow
GET	/api/v1/workflows	List workflows
GET	/api/v1/workflows/{id}	Get workflow status
POST	/api/v1/workflows/{id}/complete	Mark workflow completed
POST	/api/v1/workflows/{id}/fail	Mark workflow failed
POST	/api/v1/workflows/{id}/abort	Abort workflow
POST	/api/v1/workflows/{id}/resume	Resume workflow

Verified step-governance routes

Method	Path	Purpose
POST	/api/v1/workflows/{id}/steps/{step_id}/gate	Run a step gate check
POST	/api/v1/workflows/{id}/steps/{step_id}/complete	Mark a step complete
POST	/api/v1/workflows/{id}/steps/{step_id}/approve	Approve a gated step when enabled by tier
POST	/api/v1/workflows/{id}/steps/{step_id}/reject	Reject a gated step when enabled by tier
GET	/api/v1/workflows/approvals/pending	List pending approvals when enabled by tier

Register a workflow

curl -X POST http://localhost:8080/api/v1/workflows \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "workflow_name": "code-review-pipeline",
    "source": "langgraph",
    "trace_id": "run-abc123",
    "metadata": {
      "environment": "production"
    }
  }'

Successful creates return:

{
  "workflow_id": "wf_abc123",
  "workflow_name": "code-review-pipeline",
  "source": "langgraph",
  "status": "in_progress",
  "created_at": "2026-03-29T12:00:00Z",
  "trace_id": "run-abc123"
}

Check a step gate

POST /api/v1/workflows/{id}/steps/{step_id}/gate is the core WCP endpoint.

Verified request fields:

Field	Required	Notes
step_type	Yes	One of llm_call, tool_call, connector_call, human_task
step_name	No	Friendly step name
step_input	No	Step input payload
model	No	LLM model when relevant
provider	No	LLM provider when relevant
tokens_in, tokens_out, cost_usd	No	Optional metrics
tool_context	No	Required for per-tool governance inside tool-call steps

Verified response fields:

Field	Meaning
decision	allow, block, or require_approval
step_id	Step identifier
decision_id	Decision correlation ID
policy_ids	Policy IDs that influenced the result
reason	Human-readable reason
approval_id	HITL queue entry UUID (when decision is require_approval)
approval_url	Absolute reviewer URL; populated only when the orchestrator is booted with PORTAL_BASE_URL set (format: {PORTAL_BASE_URL}/workflows/{workflow_id}/steps/{step_id}/approve)
policies_evaluated	All checked policies
policies_matched	Policies that actually matched
cached	Deprecated back-compat flag; prefer retry_context.gate_count > 1
decision_source	"fresh" on a first evaluation, "cached" on an idempotent retry
retry_context	v7.3+ block with gate_count, completion_count, prior_completion_status, prior_output_available, first_attempt_at, last_attempt_at, last_decision, idempotency_key. See Retry Semantics & Idempotency for the full field list

Example (require_approval on first evaluation):

{
  "decision": "require_approval",
  "step_id": "step-2",
  "decision_id": "dec_wf_abc123_step-2",
  "policy_ids": ["tenant-cost-review"],
  "reason": "High-cost step requires approval",
  "approval_id": "03d5a6e7-b280-5722-8c77-526fbf015345",
  "approval_url": null,
  "cached": false,
  "decision_source": "fresh",
  "policies_evaluated": [
    {
      "policy_id": "tenant-cost-review",
      "policy_name": "Tenant Cost Review",
      "action": "require_approval",
      "risk_level": "high",
      "allow_override": false,
      "policy_description": "Flag workflow steps with unusually high estimated cost"
    }
  ],
  "policies_matched": [
    {
      "policy_id": "tenant-cost-review",
      "policy_name": "Tenant Cost Review",
      "action": "require_approval",
      "risk_level": "high",
      "allow_override": false,
      "policy_description": "Flag workflow steps with unusually high estimated cost"
    }
  ],
  "retry_context": {
    "gate_count": 1,
    "completion_count": 0,
    "prior_completion_status": "none",
    "prior_output_available": false,
    "prior_output": null,
    "prior_completion_at": null,
    "first_attempt_at": "2026-04-22T10:00:00.000Z",
    "last_attempt_at": "2026-04-22T10:00:00.000Z",
    "last_decision": "require_approval",
    "idempotency_key": ""
  }
}

approval_url is shown as null because the orchestrator in this example was not configured with PORTAL_BASE_URL. When it is configured, the value is an absolute URL of the form {PORTAL_BASE_URL}/workflows/{workflow_id}/steps/{step_id}/approve — the reviewer-side action URL for the HITL portal.

Agent Registry and Workflow Execution Views

AxonFlow also exposes orchestration-adjacent routes for agent registry inspection and workflow execution history:

Method	Path	Purpose
GET	/api/v1/agents	List available agents
GET	/api/v1/agents/{id}	Get one agent
POST	/api/v1/agents/validate	Validate agent config
GET	/api/v1/workflows/executions	List workflow executions
GET	/api/v1/workflows/executions/{id}	Get one workflow execution
GET	/api/v1/workflows/executions/tenant/{tenant_id}	Tenant-scoped execution history

These routes are useful for teams building internal orchestration tooling, plan-debugging dashboards, or operator consoles around AxonFlow.

Webhooks and Real-Time Status

Two more orchestration-adjacent surfaces matter as systems mature:

Method	Path	Availability
`GET	POST	PUT
GET	/api/v1/unified/executions/{id}/stream	Real-time execution status streaming

Those routes become especially valuable for operations teams that need approval workflows, event-driven automation, or live execution monitoring across many AI workflows.

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Missing required fields or malformed request
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions or tier restriction
NO_AGENTS_AVAILABLE	400	No agents configured for the requested topic
AGENT_NOT_FOUND	404	Specified agent does not exist
PLANNING_TIMEOUT	408	Plan generation exceeded timeout
RATE_LIMITED	429	Request rate limit exceeded
PLANNING_ERROR	500	Internal error during plan generation
EXECUTION_ERROR	500	Step execution failed
SERVICE_UNAVAILABLE	503	Orchestrator or LLM provider temporarily unavailable

Rate Limits

Tier	Requests/min	Concurrent Plans
Community	60	5
Evaluation	300	25
Enterprise	Configurable	Configurable

Rate limit headers are returned on all responses:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Related Docs

• Orchestration Overview
• WCP Overview
• Decision & Execution Replay API