Skip to main content
API docs by Redocly

AxonFlow Orchestrator API (1.1.0)

Download OpenAPI specification:Download

URL: https://getaxonflow.com/support License: Business Source License 1.1

REST API for the AxonFlow Orchestrator service - Dynamic Policy Enforcement, LLM Routing, and Multi-Agent Planning.

The Orchestrator handles:

  • Dynamic Policy Evaluation: Database-backed policy rules with risk scoring
  • LLM Routing: Intelligent routing across OpenAI, Anthropic, Bedrock, Ollama
  • Multi-Agent Planning (MAP): LLM-powered task decomposition and parallel execution
  • Response Processing: PII detection and redaction
  • Workflow Execution: Step-based workflow orchestration
  • Audit Logging: Comprehensive request/response logging

Architecture

Client → Agent → Orchestrator → LLM Providers
              ↘ MCP Connectors

The Orchestrator receives pre-authenticated requests from the Agent and handles complex processing including LLM calls and dynamic policy evaluation.

Internal API

These endpoints are typically called by the Agent service, not directly by clients. For client-facing APIs, see the Agent API specification.

Health

Service health and readiness

Health check

Returns service health status including component health:

  • Policy Engine
  • LLM Router
  • Response Processor
  • Audit Logger
  • Workflow Engine
  • Planning Engine (MAP)
  • Result Aggregator (MAP)

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "service": "axonflow-orchestrator",
  • "version": "9.8.0",
  • "timestamp": "2025-01-15T10:30:00Z",
  • "components": {
    },
  • "features": {
    }
}

Processing

Main request processing pipeline

Process orchestrator request

Main processing endpoint. Handles:

  1. Dynamic policy evaluation
  2. LLM provider routing
  3. Response processing (PII detection)
  4. Audit logging
  5. Metrics collection

Note: This endpoint is typically called by the Agent, not directly by clients. For MCP queries (request_type: mcp-query), routes to the Agent MCP handler.

Request Body schema: application/json
required
request_id
string

Unique request identifier

query
required
string

Query to process

request_type
string

Type of request

skip_llm
boolean
Default: false

Skip LLM calls (for testing)

required
object (UserContext)
required
object (ClientContext)
object

Free-form request metadata. Routing controls:

  • provider (string): preferred provider
  • strict_provider (boolean, optional): when true, hard-pins provider and disables fallback for this request. Default is false unless server env LLM_STRICT_PROVIDER_DEFAULT=true.
timestamp
string <date-time>
Array of objects (MediaContentRequest) <= 10 items

Optional media content (images) for multimodal governance analysis

Responses

Request samples

Content type
application/json
Example
{
  • "request_id": "req_12345",
  • "query": "Summarize the quarterly report",
  • "request_type": "llm_chat",
  • "user": {
    },
  • "client": {
    },
  • "context": {
    },
  • "timestamp": "2025-01-15T10:30:00Z"
}

Response samples

Content type
application/json
{
  • "request_id": "req_12345",
  • "success": true,
  • "data": "Here is the quarterly report summary...",
  • "redacted": false,
  • "policy_info": {
    },
  • "provider_info": {
    },
  • "processing_time": "1.3s"
}

Multi-Agent Planning

LLM-powered task decomposition and execution

Execute multi-agent plan

Multi-Agent Planning (MAP) endpoint for complex, multi-step tasks.

How MAP Works

  1. Decomposition: LLM analyzes query and breaks into sub-tasks
  2. Planning: Creates workflow with dependencies
  3. Execution: Runs tasks (parallel when possible)
  4. Aggregation: Synthesizes results into final response

Execution Modes

  • auto: Automatically determines parallel/sequential (recommended)
  • parallel: Force parallel execution of all independent steps
  • sequential: Force sequential step-by-step execution
  • balanced: I/O-bound connector steps parallel, LLM steps sequential
  • confirm: Every step requires explicit approval (Enterprise only)
  • step: First step auto-executes, subsequent require approval (Enterprise only)

Domains

  • travel: Flights, hotels, itineraries
  • healthcare: Medical queries
  • finance: Financial analysis
  • generic: General-purpose tasks

Plan steps are automatically routed to matching connectors based on capabilities. Community: Subject to connector limits (2 connectors). Enterprise: Unlimited connectors with multi-connector fallback support.

Requires authentication: Requests must come through the Agent.

Request Body schema: application/json
required
query
required
string

Natural language task description

domain
string
Default: "generic"
Enum: "travel" "healthcare" "finance" "generic"

Task domain for specialized handling

execution_mode
string
Default: "auto"
Enum: "auto" "parallel" "sequential" "balanced" "confirm" "step"

How to execute sub-tasks.

  • auto: Automatically determines parallel/sequential (recommended)
  • parallel: Force parallel execution of all independent steps
  • sequential: Force sequential step-by-step execution
  • balanced: I/O-bound connector steps parallel, LLM steps sequential
  • confirm: Every step requires explicit approval before execution (Enterprise only)
  • step: First step auto-executes, subsequent steps require approval (Enterprise only)
required
object (UserContext)
object
object

Responses

Request samples

Content type
application/json
Example
{
  • "query": "Find flights from NYC to LAX next week and suggest hotels",
  • "domain": "travel",
  • "execution_mode": "auto",
  • "user": {
    },
  • "client": {
    },
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "plan_id": "plan_1705312200_abc123",
  • "workflow_execution_id": "exec_xyz789",
  • "result": {
    },
  • "metadata": {
    }
}

Execute a stored plan

Executes a plan previously generated and stored via POST /api/v1/plan. The plan to execute is identified by context.plan_id in the request body. The execution mode is taken from the stored plan (not this request): auto, parallel, sequential, balanced, or the Enterprise-only HITL modes confirm / step.

Requires authentication: requests must be routed through the AxonFlow Agent (user.id must be set). The X-Tenant-ID / X-Org-ID headers set by the Agent auth chain override any identity fields in the body.

A plan can be executed once: re-executing returns 409, a cancelled plan returns 409, and an expired plan returns 410.

Request Body schema: application/json
required
query
required
string

Natural language task description

domain
string
Default: "generic"
Enum: "travel" "healthcare" "finance" "generic"

Task domain for specialized handling

execution_mode
string
Default: "auto"
Enum: "auto" "parallel" "sequential" "balanced" "confirm" "step"

How to execute sub-tasks.

  • auto: Automatically determines parallel/sequential (recommended)
  • parallel: Force parallel execution of all independent steps
  • sequential: Force sequential step-by-step execution
  • balanced: I/O-bound connector steps parallel, LLM steps sequential
  • confirm: Every step requires explicit approval before execution (Enterprise only)
  • step: First step auto-executes, subsequent steps require approval (Enterprise only)
required
object (UserContext)
object
object

Responses

Request samples

Content type
application/json
{
  • "query": "Find flights from NYC to LAX next week",
  • "domain": "travel",
  • "user": {
    },
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "plan_id": "string",
  • "version": 1,
  • "steps": [
    ],
  • "workflow_execution_id": "string",
  • "result": null,
  • "metadata": {
    },
  • "error": "string",
  • "policy_info": {
    },
  • "complexity": "medium",
  • "domain": "travel",
  • "parallel": true,
  • "status": "string"
}

Get plan execution status

Retrieve the status of a plan by ID.

Returns detailed execution status including:

  • Overall plan status (pending, executing, completed, failed, expired)
  • Step-level progress with completion percentage
  • Duration and cost tracking
  • Error details if execution failed

New in #1075: Response now includes unified execution tracking with:

  • steps array with individual step status
  • progress_percent for real-time progress
  • duration for elapsed time
  • estimated_cost_usd and actual_cost_usd for cost tracking
path Parameters
id
required
string

Plan ID (e.g., plan_1705312200_abc123)

Responses

Response samples

Content type
application/json
Example
{
  • "plan_id": "plan_1705312200_abc123",
  • "execution_id": "plan_xyz789",
  • "status": "pending",
  • "query": "Find flights from NYC to LAX",
  • "domain": "travel",
  • "total_steps": 3,
  • "completed_steps": 0,
  • "progress_percent": 0,
  • "created_at": "2025-01-15T10:00:00Z",
  • "expires_at": "2025-01-15T12:00:00Z"
}

Update a pending plan

Update a plan that has not yet been executed. Uses optimistic locking via the version field — the request must include the expected current version. If the version doesn't match, returns 409.

Only plans with status pending can be updated.

path Parameters
id
required
string

Plan ID to update

Request Body schema: application/json
required
version
required
integer

Expected current version (for optimistic locking)

execution_mode
string
Enum: "auto" "parallel" "sequential" "balanced" "confirm" "step"

New execution mode

domain
string

New domain

object

Additional metadata to set

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "execution_mode": "parallel"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "plan_id": "plan_1705312200_abc123",
  • "version": 2,
  • "status": "pending"
}

Cancel a pending plan

Cancel a plan that has not yet completed execution. Only plans with status pending or executing can be cancelled. Returns 409 if the plan is already completed or cancelled.

path Parameters
id
required
string

Plan ID to cancel

Request Body schema: application/json
optional
reason
string

Optional cancellation reason

Responses

Request samples

Content type
application/json
{
  • "reason": "User requested cancellation"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "plan_id": "plan_1705312200_abc123",
  • "status": "cancelled"
}

Get plan version history

Retrieve the version history for a plan, showing all changes made. Each version entry includes the change type, who made it, and when.

Community: Max 10 versions per plan, max 25 plans with versioning. Enterprise: Unlimited.

path Parameters
id
required
string

Plan ID

Responses

Response samples

Content type
application/json
{
  • "plan_id": "plan_1705312200_abc123",
  • "versions": [
    ]
}

Resume a paused plan (Enterprise only)

Resume execution of a plan that is paused at an approval gate. Used with confirm and step execution modes.

  • confirm mode: Every step requires explicit approval
  • step mode: First step auto-executes, subsequent steps require approval

Set approved: true to approve and execute the next step, or approved: false to reject and abort the plan.

Requires: Enterprise license.

path Parameters
id
required
string

Plan ID to resume

Request Body schema: application/json
optional
approved
boolean
Default: true

Whether to approve the pending step

Responses

Request samples

Content type
application/json
{
  • "approved": true
}

Response samples

Content type
application/json
Example
{
  • "plan_id": "plan_1705312200_abc123",
  • "status": "awaiting_approval",
  • "result": null
}

Rollback plan to a previous version (Enterprise only)

Rollback a plan to a previously saved version. This creates a new version that restores the plan state from the specified historical version.

Uses the plan's version history to retrieve the target version and applies it as the current state. Returns 409 if a concurrent modification occurred.

Requires: Enterprise license.

path Parameters
id
required
string
Example: plan_1705312200_abc123

Plan ID to rollback

version
required
integer
Example: 2

Target version number to rollback to

Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "plan_id": "plan_1705312200_abc123",
  • "version": 4,
  • "previous_version": 2,
  • "status": "pending"
}

Approve a MAP plan step (HITL parity with WCP)

Plan-scoped approval endpoint. Returns the same ApprovalResponse shape as the WCP endpoint (/api/v1/workflows/{id}/steps/{step_id}/approve) plus a plan_id field — see ADR-046 (HITL response parity).

Two underlying flows, identical response:

  • MAP confirm / step modes — backed by a WCP workflow; the handler delegates to the WCP service and projects the full retry_context, approver metadata, and policies_matched.
  • MAP legacy in-memory flow (policy-driven pause/resume, no WCP workflow registered) — handler falls back to the in-memory execution store and projects a minimal response with retry_context zero-valued and approval_id from the execution record.
path Parameters
planId
required
string
Example: plan-abc123

MAP plan ID

stepId
required
string
Example: step_0_analyze

Step ID awaiting approval

Request Body schema: application/json
optional
approved_by
string

Identity approving the step (overrides X-User-ID header)

comment
string

Audit justification. Required on WCP-backed plans (min 10 chars); if shorter, the handler auto-fills a generated audit message.

Responses

Request samples

Content type
application/json
{
  • "approved_by": "[email protected]",
  • "comment": "Approved after full audit review of the payment intent"
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_abc123",
  • "plan_id": "plan-abc123",
  • "step_id": "step_0_analyze",
  • "status": "approved",
  • "decision": "allow",
  • "reason": "Approved: High-value transfer requires oversight",
  • "approval_status": "approved",
  • "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  • "approved_by": "[email protected]",
  • "approved_at": "2026-04-22T10:05:00Z",
  • "policies_matched": [
    ],
  • "retry_context": {
    },
  • "message": "Step approved"
}

Reject a MAP plan step (HITL parity with WCP)

Plan-scoped rejection endpoint. Symmetric with the WCP endpoint (/api/v1/workflows/{id}/steps/{step_id}/reject) — same response shape (ApprovalResponse) plus plan_id. See ADR-046.

Rejection aborts the workflow / plan. On WCP-backed plans the WCP service's RejectStep handles the abort; on the legacy in-memory flow, the HITL workflow engine's AbortExecution handles it.

path Parameters
planId
required
string
stepId
required
string
Request Body schema: application/json
optional
rejected_by
string
reason
string

Audit justification. Required on WCP-backed plans (min 10 chars); auto-filled otherwise.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_abc123",
  • "plan_id": "plan-42",
  • "step_id": "step-2",
  • "status": "approved",
  • "decision": "allow",
  • "reason": "Approved: High-value transfer requires oversight",
  • "approval_status": "approved",
  • "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  • "approved_by": "[email protected]",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "[email protected]",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "policies_matched": [
    ],
  • "retry_context": {
    },
  • "message": "Step approved"
}

Agents

Agent configuration management (MAP 0.8). Enterprise only — the /api/v1/agents route family is registered only in Enterprise builds with a database connection; Community returns 404.

List all agents (Enterprise)

Returns a paginated list of all agents from the registry. In hybrid mode, includes both file-based and database-backed agents. Database agents take priority over file agents with the same name.

Enterprise only. The entire /api/v1/agents route family is registered only in Enterprise builds with a database connection; Community deployments return 404 for every /api/v1/agents path.

query Parameters
page
integer >= 1
Default: 1

Page number (1-based)

page_size
integer [ 1 .. 100 ]
Default: 20

Number of agents per page

domain
string

Filter by domain

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "pagination": {
    }
}

Create new agent (Enterprise)

Create a new agent configuration in the database. Enterprise only - requires database-backed storage.

The agent is created with version 1 and marked as active by default. A version history entry is automatically created.

Request Body schema: application/json
required
name
required
string

Agent name (lowercase, alphanumeric, hyphens, underscores)

domain
string

Agent domain

description
string
is_active
boolean
Default: true
required
object (AgentConfigSpec)

Agent configuration specification

Responses

Request samples

Content type
application/json
{
  • "name": "travel-planner",
  • "domain": "travel",
  • "description": "Travel planning and booking assistant",
  • "is_active": true,
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Get agent by ID (Enterprise)

Returns detailed information about a specific agent. The ID format is domain/name (e.g., travel/flight-booking).

Enterprise only - the /api/v1/agents family is not registered in Community.

path Parameters
id
required
string
Example: travel/flight-booking

Agent ID in format domain/name

Responses

Response samples

Content type
application/json
{
  • "id": "travel/flight-booking",
  • "name": "flight-booking",
  • "domain": "travel",
  • "description": "string",
  • "version": 0,
  • "is_active": true,
  • "config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update agent (Enterprise)

Update an existing agent configuration. Enterprise only - requires database-backed storage.

Updates increment the version number automatically. A version history entry is created for the change.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

Request Body schema: application/json
required
name
string
domain
string
description
string
is_active
boolean
object (AgentConfigSpec)

Agent configuration specification

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "domain": "string",
  • "description": "string",
  • "is_active": true,
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Delete agent (Enterprise)

Delete an agent configuration. Enterprise only - requires database-backed storage.

The deletion is recorded in the version history before removal.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "string"
}

Validate agent configuration (Enterprise)

Validates an agent configuration without creating it. Useful for dry-run validation before deployment.

Enterprise only - the /api/v1/agents family is not registered in Community.

Checks:

  • Required fields present
  • Name/domain format valid
  • Agent types valid (llm-call, connector-call)
  • LLM config complete for llm-call agents
  • Routing rules reference defined agents
Request Body schema: application/json
required
name
string
domain
string
required
object (AgentConfigSpec)

Agent configuration specification

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "domain": "string",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [ ]
}

Activate agent (Enterprise)

Activate a deactivated agent. Enterprise only - requires database-backed storage.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Deactivate agent (Enterprise)

Deactivate an agent without deleting it. Enterprise only - requires database-backed storage.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Test agent in sandbox (Enterprise)

Test an agent configuration in a sandbox environment. Enterprise only - requires database-backed storage.

Executes a test query against the agent without affecting production.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

Request Body schema: application/json
required
query
required
string

Test query to execute

object

Additional context for the query

Responses

Request samples

Content type
application/json
{
  • "query": "Search for flights from NYC to LAX",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "result": null,
  • "execution_time_ms": 0,
  • "tasks_executed": 0,
  • "errors": [
    ]
}

Get agent version history (Enterprise)

Returns the version history for an agent. Enterprise only - requires database-backed storage.

Includes all changes: create, update, delete, activate, deactivate.

path Parameters
id
required
string <uuid>

Agent ID (UUID)

query Parameters
limit
integer <= 100
Default: 50

Maximum number of versions to return

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ]
}

LLM Providers

LLM provider management

Get LLM provider status

Returns status and availability of all configured LLM providers

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Update provider routing weights

Update the routing weights for LLM providers. Weights determine the probability of routing to each provider. Weights must sum to 1.0.

Request Body schema: application/json
required
property name*
additional property
number [ 0 .. 1 ]

Responses

Request samples

Content type
application/json
{
  • "openai": 0.5,
  • "bedrock": 0.3,
  • "ollama": 0.2
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Provider weights updated"
}

List available provider types

Returns a list of available LLM provider types (factory info). This endpoint helps clients discover what provider types can be configured.

Responses

Response samples

Content type
application/json
{
  • "provider_types": [
    ]
}

List LLM providers

Returns a paginated list of configured LLM providers. Supports filtering by type and enabled status.

query Parameters
type
string
Enum: "openai" "azure-openai" "anthropic" "bedrock" "ollama" "gemini" "custom"

Filter by provider type

enabled
boolean

Filter by enabled status

page
integer
Default: 1

Page number (1-indexed)

page_size
integer <= 100
Default: 20

Items per page

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ],
  • "pagination": {
    }
}

Create LLM provider

Register a new LLM provider. API keys can be provided directly or via AWS Secrets Manager ARN for secure credential storage.

Request Body schema: application/json
required
name
required
string

Unique provider name

type
required
string
Enum: "openai" "azure-openai" "anthropic" "bedrock" "ollama" "gemini" "custom"
api_key
string

API key (mutually exclusive with api_key_secret_arn)

api_key_secret_arn
string

AWS Secrets Manager ARN for API key

endpoint
string

API endpoint URL

model
string

Default model name

region
string

AWS region (for Bedrock)

enabled
boolean
Default: true
priority
integer
Default: 100
weight
integer
Default: 100
rate_limit
integer

Max requests per second

timeout_seconds
integer
Default: 30
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "openai",
  • "api_key": "string",
  • "api_key_secret_arn": "string",
  • "endpoint": "string",
  • "model": "string",
  • "region": "string",
  • "enabled": true,
  • "priority": 100,
  • "weight": 100,
  • "rate_limit": 0,
  • "timeout_seconds": 30,
  • "settings": { }
}

Response samples

Content type
application/json
{
  • "provider": {
    }
}

Get LLM provider

Returns details for a specific LLM provider

path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "provider": {
    }
}

Update LLM provider

Update an existing LLM provider configuration. Only provided fields are updated (partial update).

path Parameters
name
required
string

Provider name

Request Body schema: application/json
required
api_key
string
api_key_secret_arn
string
endpoint
string
model
string
region
string
enabled
boolean
priority
integer
weight
integer
rate_limit
integer
timeout_seconds
integer
object

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "api_key_secret_arn": "string",
  • "endpoint": "string",
  • "model": "string",
  • "region": "string",
  • "enabled": true,
  • "priority": 0,
  • "weight": 0,
  • "rate_limit": 0,
  • "timeout_seconds": 0,
  • "settings": { }
}

Response samples

Content type
application/json
{
  • "provider": {
    }
}

Delete LLM provider

Remove an LLM provider configuration

path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get provider health

Check health status of a specific LLM provider

path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "health": {
    }
}

Test LLM provider connection

Tests a provider connection by making a simple API call. Returns success status and latency information.

path Parameters
name
required
string

Provider name

Request Body schema: application/json
optional
prompt
string

Optional test prompt (default is simple greeting)

model
string

Optional model to test with

Responses

Request samples

Content type
application/json
{
  • "prompt": "Say hello in one word.",
  • "model": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "provider": "openai",
  • "latency_ms": 245,
  • "response": "Hello!"
}

Get all providers status

Returns status information for all configured LLM providers. Includes enabled status, configuration summary, and last health check.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Get routing configuration

Get current LLM provider routing weights

Responses

Response samples

Content type
application/json
{
  • "weights": {
    }
}

Update routing weights

Update LLM provider routing weights. Weights are integers representing relative priority.

Request Body schema: application/json
required
required
object

Provider name to weight mapping

property name*
additional property
integer

Responses

Request samples

Content type
application/json
{
  • "weights": {
    }
}

Response samples

Content type
application/json
{
  • "weights": {
    }
}

Dynamic Policies

Runtime policy management

List policies

Returns a paginated list of policies with filtering support. Use this for policy management in the Customer Portal.

query Parameters
type
string
Enum: "static" "dynamic"

Filter by policy type

enabled
boolean

Filter by enabled status

search
string

Search in name and description

page
integer
Default: 1
page_size
integer <= 100
Default: 20
sort_by
string
Enum: "name" "created_at" "updated_at" "priority"
sort_dir
string
Default: "asc"
Enum: "asc" "desc"
header Parameters
X-Tenant-ID
required
string

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Create policy

Create a new policy

header Parameters
X-Tenant-ID
required
string
X-User-ID
string
Request Body schema: application/json
required
name
required
string
description
string
type
required
string
Enum: "static" "dynamic"
category
string
tier
string
Default: "tenant"
Enum: "organization" "tenant"
pattern
string

Required for static policies

action
string
Enum: "block" "require_approval" "redact" "warn" "log"
severity
string
Enum: "critical" "high" "medium" "low"
priority
integer
Default: 100
enabled
boolean
Default: true
conditions
Array of objects

Required for dynamic policies

actions
Array of objects

Required for dynamic policies

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "static",
  • "category": "string",
  • "tier": "organization",
  • "pattern": "string",
  • "action": "block",
  • "severity": "critical",
  • "priority": 100,
  • "enabled": true,
  • "conditions": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "string",
  • "name": "string",
  • "description": "string",
  • "type": "static",
  • "category": "string",
  • "tier": "system",
  • "pattern": "string",
  • "action": "block",
  • "severity": "critical",
  • "priority": 0,
  • "enabled": true,
  • "conditions": [
    ],
  • "actions": [
    ],
  • "version": 0,
  • "tenant_id": "string",
  • "organization_id": "string",
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Import policies

Bulk import policies from JSON or YAML format. Supports create or update semantics based on policy_id.

header Parameters
X-Tenant-ID
required
string
X-User-ID
string
Request Body schema: application/json
required
required
Array of objects (CreatePolicyRequest)
mode
string
Default: "upsert"
Enum: "create" "upsert"

Import mode - create only or upsert (create or update)

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ],
  • "mode": "create"
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "failed": 0,
  • "errors": [
    ]
}

Export policies

Export all policies in JSON or YAML format for backup or migration

query Parameters
format
string
Default: "json"
Enum: "json" "yaml"

Export format

type
string
Default: "all"
Enum: "static" "dynamic" "all"

Filter by policy type

header Parameters
X-Tenant-ID
required
string

Responses

Response samples

Content type
{
  • "version": "1.0",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "policies": [
    ]
}

Get policy by ID

path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "string",
  • "name": "string",
  • "description": "string",
  • "type": "static",
  • "category": "string",
  • "tier": "system",
  • "pattern": "string",
  • "action": "block",
  • "severity": "critical",
  • "priority": 0,
  • "enabled": true,
  • "conditions": [
    ],
  • "actions": [
    ],
  • "version": 0,
  • "tenant_id": "string",
  • "organization_id": "string",
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update policy

path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string
X-User-ID
string
Request Body schema: application/json
required
name
string
description
string
pattern
string
action
string
Enum: "block" "require_approval" "redact" "warn" "log"
severity
string
Enum: "critical" "high" "medium" "low"
priority
integer
enabled
boolean
conditions
Array of objects
actions
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "pattern": "string",
  • "action": "block",
  • "severity": "critical",
  • "priority": 0,
  • "enabled": true,
  • "conditions": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "string",
  • "name": "string",
  • "description": "string",
  • "type": "static",
  • "category": "string",
  • "tier": "system",
  • "pattern": "string",
  • "action": "block",
  • "severity": "critical",
  • "priority": 0,
  • "enabled": true,
  • "conditions": [
    ],
  • "actions": [
    ],
  • "version": 0,
  • "tenant_id": "string",
  • "organization_id": "string",
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete policy

path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string
X-User-ID
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Test policy against input

Test how a specific policy evaluates against sample input

path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string
Request Body schema: application/json
required
query
required
string

Input to evaluate

context
object

Additional context

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "context": { }
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "applied_policies": [
    ],
  • "risk_score": 1,
  • "required_actions": [
    ],
  • "processing_time_ms": 0,
  • "database_accessed": true
}

Get policy version history

Returns version history for a policy. Community edition limited to 5 versions.

path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string

Responses

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "versions": [
    ],
  • "count": 0
}

List active dynamic policies

Returns the active dynamic policies visible to the CALLING tenant: the tenant's own policies plus the shared global/default baseline. Policies owned by other tenants are never returned in the same response, and requests without a resolvable tenant are rejected with 401 (fail closed).

The tenant scope is read from the X-Tenant-ID header. When the request arrives through the AxonFlow Agent, that header is set from the validated credential and overwrites any client-supplied value, so the caller cannot choose the scope. The orchestrator itself does not authenticate this route, so a caller with direct network access to the orchestrator can name a tenant — deploy the orchestrator on a private network behind the Agent.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Test policy evaluation

Test how dynamic policies evaluate a sample request

Request Body schema: application/json
required
query
required
string
object (UserContext)
request_type
string

Responses

Request samples

Content type
application/json
{
  • "query": "SELECT * FROM customers WHERE credit_score < 500",
  • "user": {},
  • "request_type": "sql"
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "applied_policies": [
    ],
  • "risk_score": 0.25,
  • "required_actions": [ ],
  • "processing_time_ms": 3
}

Workflows

Workflow execution engine

Execute a workflow

Execute a defined workflow with input parameters

Request Body schema: application/json
required
required
object (Workflow)
object
object (UserContext)

Responses

Request samples

Content type
application/json
{
  • "workflow": {
    },
  • "input": {
    },
  • "user": {}
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "workflow_name": "string",
  • "status": "pending",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "steps": [
    ],
  • "output": { }
}

Get workflow execution

Get details of a specific workflow execution

path Parameters
id
required
string
Example: exec_abc123

Workflow execution ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "workflow_name": "string",
  • "status": "pending",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "steps": [
    ],
  • "output": { }
}

List workflow executions

List recent workflow executions

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Maximum number of executions to return

Responses

Response samples

Content type
application/json
{
  • "executions": [
    ],
  • "count": 0
}

Get tenant workflow executions

Get workflow executions for a specific tenant

path Parameters
tenant_id
required
string

Tenant identifier

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "count": 0,
  • "executions": [
    ]
}

Workflow Control Plane

Governance gates for external orchestrators (LangChain, LangGraph, CrewAI). "LangChain runs the workflow. AxonFlow decides when it's allowed to move forward."

Features:

  • Register workflows from external orchestrators
  • Check step gates before each workflow step
  • Apply policies at step transitions (allow/block/require_approval)
  • Track workflow lifecycle (in_progress/completed/aborted/failed)

Create a workflow

Register a new workflow from an external orchestrator (LangChain, LangGraph, CrewAI). Returns a workflow_id to use for subsequent step gate checks.

Request Body schema: application/json
required
workflow_name
required
string

Human-readable name for the workflow

source
string
Default: "external"
Enum: "langgraph" "langchain" "crewai" "external"

Source orchestrator

trace_id
string <= 255 characters

External trace ID for correlation with Langsmith, Datadog, or OpenTelemetry

object

Additional workflow metadata

Responses

Request samples

Content type
application/json
{
  • "workflow_name": "code-review-pipeline",
  • "source": "langgraph",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_abc123",
  • "workflow_name": "code-review-pipeline",
  • "status": "in_progress",
  • "started_at": "2026-01-17T10:00:00Z"
}

List workflows

List workflows with optional filters

query Parameters
status
string
Enum: "in_progress" "completed" "aborted" "failed"

Filter by status

source
string
Enum: "langgraph" "langchain" "crewai" "external"

Filter by source

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of workflows to return

offset
integer
Default: 0

Number of workflows to skip

trace_id
string

Filter by external trace ID

Responses

Response samples

Content type
application/json
{
  • "workflows": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Get workflow status

Get the current status of a workflow including all step decisions

path Parameters
workflow_id
required
string
Example: wf_abc123

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "workflow_id": "string",
  • "workflow_name": "string",
  • "source": "langgraph",
  • "status": "in_progress",
  • "trace_id": "string",
  • "current_step_index": 0,
  • "total_steps": 0,
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "steps": [
    ]
}

Check step gate

Check if a workflow step is allowed to proceed. Returns a decision (allow/block/require_approval) based on policy evaluation.

Call this BEFORE executing each step in your external orchestrator.

The response always includes a retry_context block (Issue #1673 Phase 1) carrying first-class retry state: gate count, prior completion status, first/last attempt timestamps, last decision, and the idempotency_key. Callers that need to unambiguously detect retries or uncertain-territory scenarios should prefer retry_context over the deprecated cached boolean.

path Parameters
workflow_id
required
string
Example: wf_abc123

Workflow ID

step_id
required
string
Example: step-1

Step ID (unique within workflow)

query Parameters
include_prior_output
boolean
Default: false
Example: include_prior_output=true

Opt-in (Issue #1673 Phase 1) — when true and a prior /complete landed for this step, retry_context.prior_output is populated with the stored output so the agent can short-circuit re-execution. Default false because prior output may be large or sensitive.

Request Body schema: application/json
required
step_name
string

Human-readable step name (optional)

step_type
required
string
Enum: "llm_call" "tool_call" "connector_call" "human_task"

Type of step

object

Input data for the step (for policy evaluation)

model
string

LLM model being used

provider
string

LLM provider being used

tokens_in
integer

Estimated input tokens for the step (used at gate time)

tokens_out
integer

Estimated output tokens for the step (used at gate time)

cost_usd
number <double>

Estimated cost in USD for the step (used at gate time)

object (ToolContext)

Tool-level context for per-tool governance within tool_call steps.

retry_policy
string
Default: "idempotent"
Enum: "idempotent" "reevaluate"

Controls behavior on repeated calls for the same (workflow_id, step_id). Default ("idempotent"): return cached decision from prior evaluation. "reevaluate": force fresh policy evaluation regardless of prior decision.

idempotency_key
string <= 255 characters

Optional caller-supplied opaque business-level key (Issue #1673 Phase 2). Recorded on the first /gate call that sets it; immutable for the step's lifetime. Subsequent /gate and /complete calls MUST pass the same key or receive 409 IDEMPOTENCY_KEY_MISMATCH. Use business-meaningful values like payment:wire:invoice-7721, not request IDs.

Responses

Request samples

Content type
application/json
{
  • "step_name": "Generate Code",
  • "step_type": "llm_call",
  • "model": "gpt-4",
  • "provider": "openai",
  • "step_input": {
    }
}

Response samples

Content type
application/json
Example
{
  • "decision": "allow",
  • "step_id": "step-1",
  • "decision_id": "dec_xyz789"
}

Mark step completed

Mark a workflow step as completed after successful execution. Request body is optional.

path Parameters
workflow_id
required
string

Workflow ID

step_id
required
string

Step ID

Request Body schema: application/json
object

Output data from the step

tokens_in
integer

Actual input tokens consumed by the step (overrides gate-time estimate)

tokens_out
integer

Actual output tokens produced by the step (overrides gate-time estimate)

cost_usd
number <double>

Actual cost in USD for the step (overrides gate-time estimate)

idempotency_key
string <= 255 characters

Optional caller-supplied key (Issue #1673 Phase 2). Must match the key recorded on the step's earlier /gate call. Mismatch returns 409 IDEMPOTENCY_KEY_MISMATCH.

object

Free-form metadata captured at step-completion time — useful for audit context the gate-time data didn't have (post-execution latency from a downstream service, retry attempt counters, etc.). Treat as opaque on the client.

Responses

Request samples

Content type
application/json
{
  • "output": {
    },
  • "tokens_in": 150,
  • "tokens_out": 45,
  • "cost_usd": 0.0023
}

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found"
}

Complete workflow

Mark the workflow as completed

path Parameters
workflow_id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found"
}

Mark workflow as failed

Marks the workflow as failed with an optional reason (defaults to Failed when the body is empty or omitted). Tenant/org scoping comes from the X-Tenant-ID / X-Org-ID headers. Failing a workflow that is already in a terminal state returns 409.

path Parameters
workflow_id
required
string

Workflow ID

Request Body schema: application/json
optional
reason
string

Reason for the failure (defaults to "Failed")

Responses

Request samples

Content type
application/json
{
  • "reason": "Downstream connector unrecoverable"
}

Response samples

Content type
application/json
{
  • "workflow_id": "string",
  • "status": "failed",
  • "message": "Workflow marked as failed",
  • "reason": "string"
}

Abort workflow

Abort the workflow with an optional reason

path Parameters
workflow_id
required
string

Workflow ID

Request Body schema: application/json
reason
string

Reason for aborting

Responses

Request samples

Content type
application/json
{
  • "reason": "Step blocked by policy"
}

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found"
}

Resume workflow

Resume a workflow after approval (Enterprise feature)

path Parameters
workflow_id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found"
}

List step-gate checkpoints for a workflow

Returns all checkpoints for a workflow, ordered by step_index. Checkpoints are created automatically at each step gate evaluation. Available in all tiers (Community, Evaluation, Enterprise).

path Parameters
workflow_id
required
string

Responses

Response samples

Content type
application/json
{
  • "checkpoints": [
    ],
  • "workflow_id": "string"
}

Resume workflow from last checkpoint (Evaluation+)

Re-evaluates the step gate at the last resumable checkpoint with current policies. The step gate uses retry_policy=reevaluate internally.

path Parameters
workflow_id
required
string

Responses

Response samples

Content type
application/json
{
  • "workflow_id": "string",
  • "resumed_from_checkpoint": "string",
  • "resumed_from_index": 0,
  • "new_decision": "allow",
  • "decision_source": "string",
  • "resume_count": 0,
  • "message": "string"
}

Resume workflow from specific checkpoint (Enterprise)

Re-evaluates the step gate at a specific checkpoint with current policies. Enterprise only.

path Parameters
workflow_id
required
string
checkpoint_id
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "workflow_id": "string",
  • "resumed_from_checkpoint": "string",
  • "resumed_from_index": 0,
  • "new_decision": "allow",
  • "decision_source": "string",
  • "resume_count": 0,
  • "message": "string"
}

Approve a pending workflow step

Approve a workflow step that is waiting for human approval. This allows the workflow to proceed past the approval gate.

path Parameters
workflowId
required
string
Example: wf_abc123

Workflow ID

stepId
required
string
Example: step-2

Step ID awaiting approval

Request Body schema: application/json
required
comment
required
string >= 10 characters

Audit justification for approving the step (minimum 10 characters after trimming)

approved_by
string

User ID of the approver

Responses

Request samples

Content type
application/json
{
  • "comment": "Approved after reviewing output",
  • "approved_by": "user-456"
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_abc123",
  • "step_id": "step-2",
  • "status": "approved",
  • "decision": "allow",
  • "reason": "Approved: High-value transfer requires oversight",
  • "approval_status": "approved",
  • "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  • "approved_by": "[email protected]",
  • "approved_at": "2026-04-22T10:05:00Z",
  • "policies_matched": [
    ],
  • "retry_context": {
    },
  • "message": "Step approved"
}

Reject a pending workflow step

Reject a workflow step that is waiting for human approval. This blocks the step and may abort the workflow depending on configuration.

path Parameters
workflowId
required
string
Example: wf_abc123

Workflow ID

stepId
required
string
Example: step-2

Step ID awaiting approval

Request Body schema: application/json
required
reason
required
string >= 10 characters

Audit justification for rejecting the step (minimum 10 characters after trimming)

rejected_by
string

User ID of the rejector

Responses

Request samples

Content type
application/json
{
  • "reason": "Output contains PII that was not redacted",
  • "rejected_by": "user-456"
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_abc123",
  • "step_id": "step-2",
  • "status": "rejected",
  • "decision": "block",
  • "reason": "Rejected: Output contains PII that was not redacted",
  • "approval_status": "rejected",
  • "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  • "rejected_by": "[email protected]",
  • "rejected_at": "2026-04-22T10:05:00Z",
  • "policies_matched": [
    ],
  • "retry_context": {
    },
  • "message": "Step rejected, workflow aborted"
}

List pending approvals (WCP plane)

List workflow steps currently awaiting human approval for the caller's tenant (all planes). Cross-reference the MAP-plane equivalent at /api/v1/plans/approvals/pending, which scopes to MAP-backed workflows and populates plan_id on every entry.

Available on Evaluation+ licenses. Community without an Evaluation license has no approval queue to list.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

Responses

Response samples

Content type
application/json
{
  • "pending_approvals": [
    ],
  • "count": 1
}

List pending approvals (MAP plane)

List steps currently awaiting human approval for MAP-backed workflows — workflows whose metadata carries a plan_id (MAP confirm / step mode). Every returned entry has plan_id populated; this is the intentional asymmetry with the WCP-plane listing at /api/v1/workflows/approvals/pending, mirroring the approve/reject asymmetry established in Issue #1677 / ADR-046.

Reviewer integrators that need to render plan context can read plan_id directly without a second lookup; clients that want a plane-neutral view can use /api/v1/hitl/queue instead.

Available on Evaluation+ licenses (same tier gate as the MAP /steps/{step_id}/approve and /steps/{step_id}/reject endpoints).

query Parameters
plan_id
string

Filter to a single plan_id — returns only steps waiting on that plan.

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

Responses

Response samples

Content type
application/json
{
  • "pending_approvals": [
    ],
  • "count": 1
}

Connectors

Connector marketplace

List available connectors

List connectors from the marketplace

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get connector details

Get detailed information about a connector

path Parameters
id
required
string

Connector identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "installed": true,
  • "healthy": true
}

Install a connector

Install a connector from the marketplace

path Parameters
id
required
string

Connector identifier

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Invalid request body"
}

Uninstall a connector

Uninstall an installed connector

path Parameters
id
required
string

Connector identifier

Responses

Check connector health

Check health status of a connector

path Parameters
id
required
string

Connector identifier

Responses

Response samples

Content type
application/json
{
  • "healthy": true,
  • "latency_ms": 0
}

Audit

Audit log search and retrieval

Search audit logs

Search audit logs by various criteria. The tenant scope is always forced from the X-Tenant-ID header (the body cannot override it); requests without the header are rejected with 401. user_email and client_id are case-insensitive partial (ILIKE substring) matches. The search start time is clamped to the tenant's tier-based retention window.

Role-scoped reads (#2922): the caller's read scope is resolved server-side. admin/owner read the full tenant trail; every other role — and any caller without a validated per-user identity — reads only their own user_email rows (fail-closed). A non-admin's user_email filter can only narrow the result to their own identity, never widen it to another user's rows. Callers without any resolvable identity receive an empty entries array. The role/scope is trusted only over the internal agent→orchestrator proxy-auth channel, never a client-forwarded header.

Single-operator deployments (#3060): DEPLOYMENT_MODE=community reads tenant-wide unconditionally, and DEPLOYMENT_MODE=community-saas reads tenant-wide for requests that arrived over the agent gateway (proven by the internal proxy-auth token) — in that mode the organization, tenant and credential are one cs_<uuid>, so tenant-wide is that single evaluator's own data. A community-saas request that reaches the orchestrator directly stays least-privilege. Read scope is a separate axis from administrative authority: a community-saas caller reads tenant-wide here and is still denied (403) the whole-tenant compliance exports and the cost/usage/execution family.

Method: this endpoint is POST-only (its criteria are a JSON body). A GET returns 405 with Allow: POST, OPTIONS.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Request Body schema: application/json
required
user_email
string

Case-insensitive partial (ILIKE substring) match

client_id
string

Case-insensitive partial (ILIKE substring) match

start_time
string <date-time>

Window lower bound; clamped to the tenant's tier-based retention cutoff when earlier (or when omitted)

end_time
string <date-time>
action
string

Filter by policy decision. The value is normalized to its canonical verdict (allowed, blocked, redacted, needs_approval, error) and expanded to every historical DB spelling of that verdict, so it matches both current and legacy rows.

session_id
string

Exact match on the first-class session_id column — used to drill into a session-summary bucket's raw events (#2857).

limit
integer
Default: 100
offset
integer >= 0
Default: 0

Pagination offset — number of audit-log rows to skip from the start of the result set. Pair with limit to walk multi-page audit reads.

decision_id
string

Filter audit reads to a specific governance decision id (mints from MCPCheckInputResponse / MCPCheckOutputResponse etc.). Matches policy_details->>'decision_id'. Useful when correlating a specific request through its full audit trail.

override_id
string

Filter to audit entries that recorded an override-used event for this override id (matches policy_details->>'override_id').

policy_name
string

Filter to audit entries where this policy fired. Matches the three shapes audit writers store in the policy_details JSONB: the scalar policy_details.policy_name, the CSV string policy_details.policy_names, and policy_details.policy_matches[*].policy_name (workflow step gates + decision records).

Responses

Request samples

Content type
application/json
{
  • "user_email": "[email protected]",
  • "client_id": "analytics-app",
  • "start_time": "2025-01-01T00:00:00Z",
  • "end_time": "2025-01-15T23:59:59Z",
  • "action": "blocked",
  • "session_id": "sess-4f6a2c",
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total": 235,
  • "limit": 100,
  • "offset": 0
}

Get audit compliance summary

Returns aggregated compliance summary statistics for a given date range. Includes total event counts, breakdowns by severity and action type, top triggered policies, and an overall compliance score.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier for scoping results. Required to prevent cross-tenant data aggregation. There is no fallback header: the X-Org-ID fallback was removed in v6.2.0, and a request without X-Tenant-ID is rejected with 400.

Request Body schema: application/json
required
start_time
required
string <date-time>

Start of date range (RFC3339)

end_time
required
string <date-time>

End of date range (RFC3339, must be after start_time)

Responses

Request samples

Content type
application/json
{
  • "start_time": "2026-01-01T00:00:00Z",
  • "end_time": "2026-04-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "total_events": 1523,
  • "by_severity": {
    },
  • "by_action": {
    },
  • "top_policies": [
    ],
  • "compliance_score": 98.5
}

Get tenant audit logs

Get recent audit logs for a specific tenant. The URL tenant must match the session tenant carried in the X-Tenant-ID header: a missing header is rejected with 401 (fail-closed), and a mismatch with 403. Results are clamped to the tenant's tier-based retention window.

path Parameters
tenant_id
required
string
Example: tenant-abc

Tenant identifier (must equal the X-Tenant-ID header value)

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 50

Maximum number of rows to return (1-1000)

page_size
integer [ 1 .. 1000 ]
Deprecated

Deprecated alias for limit (1-1000); ignored when limit is supplied. Kept for backward compatibility.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Record a tool call audit entry

Records a non-LLM tool call (API calls, webhooks, MCP tool executions by external orchestrators) in the AxonFlow audit trail. Only tool_name is required; all other fields are optional.

Authorizations:
basicAuth
header Parameters
X-Tenant-ID
required
string

Tenant identifier (must match the client ID from Basic auth credentials)

X-Axonflow-Proxy-Auth
required
string

Internal-service HMAC token proving the request was routed through the AxonFlow Agent gateway (derived from AXONFLOW_INTERNAL_SERVICE_SECRET). Enforced fail-closed in every non-Community deployment: a missing or invalid token — or an unconfigured secret — is rejected with 403, in addition to the Basic auth requirement below. Community deployments without the secret configured skip this check.

Idempotency-Key
string [ 1 .. 256 ] characters ^[A-Za-z0-9_.:\-/]+$

Optional per-request dedup token. When supplied, the platform caches the response for 24h and returns it byte-for-byte on subsequent requests carrying the same key + same authenticated tenant. A cache hit adds an Idempotent-Replayed: true response header. Pattern: ^[A-Za-z0-9_.:\-/]+$, max 256 chars. 5xx responses are not cached so the caller's retry can hit a fresh attempt.

Request Body schema: application/json
required
tool_name
required
string

Name of the tool that was called

caller_name
string

Which client/integration made this call (e.g. claude_code, codex, cursor, openclaw). Replaces tool_type (#2912), which was misnamed for this purpose — every real caller used it to identify itself, not to describe a property of the tool.

tool_type
string
Deprecated

Deprecated — use caller_name instead. Accepted as a legacy input fallback when caller_name is not supplied.

input
object

Input data sent to the tool

output
object

Output data returned by the tool

workflow_id
string

Associated workflow ID

step_id
string

Associated workflow step ID

user_id
string

User who triggered the tool call

duration_ms
integer <int64>

Duration of the tool call in milliseconds

policies_applied
Array of strings

List of policy names applied during the tool call

success
boolean

Whether the tool call succeeded

error_message
string

Error message if the tool call failed

Responses

Request samples

Content type
application/json
{
  • "tool_name": "getUserInfo",
  • "caller_name": "claude_code",
  • "input": { },
  • "output": { },
  • "workflow_id": "wf_abc123",
  • "step_id": "step-3",
  • "user_id": "[email protected]",
  • "duration_ms": 45,
  • "policies_applied": [
    ],
  • "success": true,
  • "error_message": ""
}

Response samples

Content type
application/json
{
  • "audit_id": "audit_1710432000_abcd1234",
  • "status": "recorded",
  • "timestamp": "2026-03-14T12:00:00Z"
}

Export audit logs (CSV or JSON)

Exports audit logs as a downloadable file. Filters mirror /api/v1/audit/search (same ILIKE user/client matching, canonical action expansion, JSONB policy filters and date range), so an export always reconciles with the on-screen search for the same filters. Tenant scope is forced from the X-Tenant-ID header.

The export is capped at 50,000 rows; when the cap is hit the response carries the X-Audit-Export-Truncated: true and X-Audit-Export-Row-Cap headers so callers can warn that the file is partial. Free-text CSV cells are formula-escaped (leading =, +, -, @, tab or CR is prefixed with ') to neutralize spreadsheet formula injection.

query Parameters
format
string
Default: "json"
Enum: "csv" "json"

Export format. Defaults to json.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Request Body schema: application/json
optional

Optional filters. An empty body exports the whole tenant window (within the tier retention floor). A present-but-malformed body is a 400.

user_email
string

Case-insensitive partial (ILIKE substring) match

client_id
string

Case-insensitive partial (ILIKE substring) match

action
string

Canonical verdict filter (allowed, blocked, redacted, needs_approval, error); expanded to all historical DB spellings of that verdict.

session_id
string

Exact match on the first-class session_id column

decision_id
string

Matches policy_details->>'decision_id'

policy_name
string

Same three-shape policy_details match as /api/v1/audit/search

override_id
string

Matches policy_details->>'override_id'

start_time
string <date-time>
end_time
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "action": "blocked",
  • "start_time": "2026-06-01T00:00:00Z",
  • "end_time": "2026-06-30T23:59:59Z"
}

Response samples

Content type
{
  • "entries": [
    ],
  • "count": 0,
  • "truncated": true,
  • "row_cap": 50000
}

Per-action audit report

Aggregates audit logs for a window into per-action counts, average latency, and top policies, tenant-scoped and optionally filtered by user and a single canonical action. Counts reconcile with /api/v1/audit/search for the same filters.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Request Body schema: application/json
required
start_time
required
string <date-time>

Window start (RFC3339)

end_time
required
string <date-time>

Window end (RFC3339, must be after start_time; range at most 1 year)

user_email
string

Optional case-insensitive partial match

action
string

Optional single canonical action filter

Responses

Request samples

Content type
application/json
{
  • "start_time": "2026-06-01T00:00:00Z",
  • "end_time": "2026-06-30T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "tenant_id": "tenant-abc",
  • "start_time": "2026-06-01T00:00:00Z",
  • "end_time": "2026-06-30T23:59:59Z",
  • "total": 1523,
  • "by_action": {
    },
  • "avg_latency_ms": 245.7,
  • "top_policies": [
    ]
}

Session-level usage summary (Enterprise)

Enterprise — session-level usage reporting (#2759). The Community build mounts the same route but returns 501 Not Implemented.

Buckets audit logs into per-session aggregates for the date window: a bucket is per-session when session_id is present on its rows, otherwise rows without a session id fall back to a per-user-day bucket (the day field is set instead of session_id). Buckets are capped at bucket_limit (most-recent activity first); truncated is true when the window held more buckets than the cap — narrow the window or raise limit. Drill into a bucket's raw events via POST /api/v1/audit/search with its session_id (#2857).

The window start is clamped to the tenant's tier retention floor, like /api/v1/audit/search and /api/v1/audit/export.

query Parameters
start_date
required
string <date>
Example: start_date=2026-07-01

Window start, calendar day (YYYY-MM-DD)

end_date
required
string <date>
Example: end_date=2026-07-07

Window end, calendar day (YYYY-MM-DD), inclusive

user_email
string

Case-insensitive partial (ILIKE substring) filter

limit
integer >= 1
Default: 200

Caps the number of returned buckets. Default 200. Values above the server max (1000) are clamped; the effective bound is echoed back as bucket_limit. A non-positive or non-integer value is a 400.

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "user_email": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "buckets": [
    ],
  • "bucket_limit": 0,
  • "truncated": true
}

Get a single audit entry by ID

Returns the full audit entry for the given id, tenant-scoped by the X-Tenant-ID header. A record that exists but belongs to another tenant returns 404 (not 403), so the endpoint cannot be used as a cross-tenant existence oracle. Literal /api/v1/audit/* routes (search, export, report, session-summary, tenant, tool-call) are matched before this parameterized path — including GET /api/v1/audit/search, which answers 405 rather than being swallowed here as an id of "search" (#3060).

Role-scoped reads (#2922): a non-tenant-wide caller may fetch only their own rows; a record belonging to another user returns the same 404 as a missing one (non-oracle). See POST /api/v1/audit/search for the deployment-mode carve-outs.

path Parameters
id
required
string

Audit entry id

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "request_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user_id": 0,
  • "user_email": "string",
  • "user_role": "string",
  • "client_id": "string",
  • "tenant_id": "string",
  • "org_id": "string",
  • "request_type": "string",
  • "query": "string",
  • "query_hash": "string",
  • "policy_decision": "string",
  • "policy_details": { },
  • "provider": "string",
  • "model": "string",
  • "response_time_ms": 0,
  • "tokens_used": 0,
  • "cost": 0.1,
  • "redacted_fields": [
    ],
  • "error_message": "string",
  • "response_sample": "string",
  • "compliance_flags": [
    ],
  • "security_metrics": { },
  • "decision_id": "string",
  • "plane": "string",
  • "correlation_id": "string",
  • "transfer_basis": "string",
  • "data_residency": "string",
  • "session_id": "string"
}

SEBI Compliance

SEBI AI/ML Guidelines compliance and DPDP Act 2023 audit exports. Enterprise feature for Indian financial services compliance.

Get SEBI compliance dashboard

Returns a comprehensive SEBI compliance dashboard including:

  • Overall compliance score and status
  • 5-year retention status
  • PII detection/redaction metrics (PAN, Aadhaar)
  • Policy violation summary with trend
  • HITL review queue

Enterprise Feature: Available only for Indian financial services deployments.

Responses

Response samples

Content type
application/json
{
  • "framework": "SEBI_DPDP_COMBINED",
  • "overall_score": 85,
  • "overall_status": "COMPLIANT",
  • "last_audit_export": "2024-12-01T10:00:00Z",
  • "retention_status": {
    },
  • "violations_summary": {
    },
  • "pii_summary": {
    },
  • "hitl_reviews_pending": 3
}

Export SEBI audit data

Export audit data for SEBI regulatory submission. Supports:

  • Multiple compliance frameworks (SEBI AI/ML, DPDP, Combined)
  • Various data types (policy violations, LLM calls, decision chain, HITL, PII redactions)
  • Multiple export formats (JSON, CSV, XML)
  • Optional PII redaction for external auditors

Large exports are processed asynchronously. Poll the export status endpoint to check completion and get the download URL.

5-Year Retention: Per SEBI AI/ML Guidelines, all audit data is retained for minimum 5 years (1825 days).

Request Body schema: application/json
required
start_date
required
string <date-time>

Start of export period (inclusive)

end_date
required
string <date-time>

End of export period (inclusive)

data_types
Array of strings (SEBIAuditDataType)
Items Enum: "policy_violations" "llm_calls" "decision_chain" "hitl_oversight" "pii_redactions" "all"

Types of audit data to export (defaults to all)

format
string (SEBIExportFormat)
Enum: "json" "csv" "xml"

Export output format

framework
string (SEBIComplianceFramework)
Enum: "SEBI_AI_ML" "DPDP_ACT_2023" "SEBI_DPDP_COMBINED"

SEBI compliance framework identifier

include_archived
boolean
Default: false

Include records from cold storage

redact_pii
boolean
Default: false

Redact PII in export (for external auditors)

object (SEBIAuditExportFilters)

Optional filters for audit exports

Responses

Request samples

Content type
application/json
{
  • "start_date": "2024-01-01T00:00:00Z",
  • "end_date": "2024-12-31T23:59:59Z",
  • "data_types": [
    ],
  • "format": "json",
  • "framework": "SEBI_DPDP_COMBINED",
  • "redact_pii": false
}

Response samples

Content type
application/json
{
  • "export_id": "exp_abc123",
  • "status": "processing",
  • "framework": "SEBI_DPDP_COMBINED",
  • "metadata": {
    }
}

Get export status

Get the status of an asynchronous SEBI audit export. When status is "completed", the download_url will be provided.

path Parameters
export_id
required
string
Example: exp_abc123

Export ID from the export request

Responses

Response samples

Content type
application/json
{
  • "export_id": "exp_abc123",
  • "status": "completed",
  • "framework": "SEBI_DPDP_COMBINED",
  • "download_url": "/api/v1/sebi/audit/export/exp_abc123/download",
  • "expires_at": "2024-12-08T14:00:00Z",
  • "summary": {
    }
}

Get retention status

Get the 5-year retention compliance status for all audit data types.

SEBI AI/ML Guidelines require:

  • All AI/ML decisions retained for 5 years
  • Audit trail for human oversight
  • Decision chain tracing

This endpoint reports compliance status for each data type.

Responses

Response samples

Content type
application/json
{
  • "org_id": 123,
  • "framework": "SEBI_AI_ML",
  • "compliance_status": "COMPLIANT",
  • "status": [
    ]
}

Check compliance readiness

Validate organization readiness for SEBI regulatory audit.

Checks include:

  • Retention configuration (5-year minimum)
  • PII detection policies
  • Human oversight mechanisms
  • Audit logging completeness
  • Decision chain tracing

Returns a score (0-100) and actionable recommendations.

Responses

Response samples

Content type
application/json
{
  • "ready": true,
  • "score": 85,
  • "checks": [
    ],
  • "recommendations": [
    ]
}

RBI Compliance

RBI FREE-AI Framework compliance for Indian banking institutions. Enterprise feature providing AI System Registry, Model Validation, Incident Management, Kill Switch, Board Reporting, and Audit Export.

Get RBI compliance dashboard

Returns RBI FREE-AI Framework compliance dashboard with module health status.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "module": "string",
  • "components": { }
}

List AI systems

List all registered AI systems for the organization. Per RBI FREE-AI: All AI systems must be registered with board approval.

query Parameters
risk_category
string
Enum: "low" "medium" "high"
deployment_status
string
Enum: "development" "sandbox" "canary" "production" "deprecated"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register AI system

Register a new AI system in the RBI compliance registry.

Request Body schema: application/json
required
system_id
required
string
risk_mitigation
object
recommendations
Array of strings
created_by
string
created_at
string <date-time>
updated_at
string <date-time>
submitted_at
string <date-time>
submitted_by
string
approved_at
string <date-time>
approved_by
string
rejected_at
string <date-time>
rejected_by
string
rejection_reason
string

Responses

Request samples

Content type
application/json
{
  • "system_id": "string",
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "system_version": "string",
  • "description": "string",
  • "risk_category": "low",
  • "deployment_status": "development",
  • "model_type": "string",
  • "model_provider": "string",
  • "use_case": "string",
  • "board_approval_required": true,
  • "board_approval_status": "not_required",
  • "last_validation_date": "2019-08-24",
  • "next_validation_due": "2019-08-24",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get AI system

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "system_version": "string",
  • "description": "string",
  • "risk_category": "low",
  • "deployment_status": "development",
  • "model_type": "string",
  • "model_provider": "string",
  • "use_case": "string",
  • "board_approval_required": true,
  • "board_approval_status": "not_required",
  • "last_validation_date": "2019-08-24",
  • "next_validation_due": "2019-08-24",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update AI system

path Parameters
id
required
string
Request Body schema: application/json
required
system_id
required
string
risk_mitigation
object
recommendations
Array of strings
created_by
string
created_at
string <date-time>
updated_at
string <date-time>
submitted_at
string <date-time>
submitted_by
string
approved_at
string <date-time>
approved_by
string
rejected_at
string <date-time>
rejected_by
string
rejection_reason
string

Responses

Request samples

Content type
application/json
{
  • "system_id": "string",
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Delete AI system

path Parameters
id
required
string

Responses

List model validations

List model validation records per RBI FREE-AI Section 3.2.

Responses

Create validation record

Responses

List AI incidents

List AI incidents per RBI FREE-AI incident management requirements.

Responses

Report AI incident

Responses

List kill switches

List active and inactive kill switches for emergency AI disable.

Responses

Activate kill switch

Emergency kill switch activation per RBI FREE-AI guidelines. Immediately halts all AI operations for specified scope.

Responses

Deactivate kill switch

path Parameters
id
required
string

Responses

List board reports

List board reports per RBI FREE-AI Section 6.1 requirements.

Responses

Generate board report

Responses

List audit exports

List audit exports with retention per RBI FREE-AI requirements.

query Parameters
limit
integer >= 1
Default: 100

Maximum number of records to return. Defaults vary by endpoint; see per-endpoint description for the cap.

offset
integer >= 0
Default: 0

Number of records to skip from the start of the result set. Pair with limit to walk multi-page reads.

header Parameters
X-Org-ID
required
string
Example: travel-us

Organization scope for this request. Stamped by the AxonFlow Agent gateway from the cryptographically validated client credential (Set, not Add, so any client-supplied value is overwritten), so it is not client-selectable and carries no cross-org override capability on this route. The orchestrator fails closed with 401 when it is absent or blank; there is no query-string equivalent.

Responses

Response samples

Content type
application/json
{
  • "exports": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create audit export

Create a new RBI audit export. Supports full or incremental exports in JSON, CSV, or XML format. When cloud storage is configured, exports are uploaded to S3/GCS/Azure and a presigned download URL is generated.

header Parameters
X-Org-ID
required
string
Example: travel-us

Organization scope for this request. Stamped by the AxonFlow Agent gateway from the cryptographically validated client credential (Set, not Add, so any client-supplied value is overwritten), so it is not client-selectable and carries no cross-org override capability on this route. The orchestrator fails closed with 401 when it is absent or blank; there is no query-string equivalent.

Request Body schema: application/json
required
export_type
required
string
Enum: "full" "incremental"

Type of audit export

format
required
string
Enum: "json" "csv" "xml"

Export file format

start_date
string <date-time>

Start of date range (for incremental exports)

end_date
string <date-time>

End of date range (for incremental exports)

requested_by
string

User or service requesting the export

purpose
string

Purpose of the export (for audit trail)

Responses

Request samples

Content type
application/json
{
  • "export_type": "full",
  • "format": "json",
  • "requested_by": "compliance-officer",
  • "purpose": "Quarterly RBI audit"
}

Response samples

Content type
application/json
{
  • "export": {
    }
}

Get audit export status

Get the status and details of a specific audit export.

path Parameters
export_id
required
string
header Parameters
X-Org-ID
required
string
Example: travel-us

Organization scope for this request. Stamped by the AxonFlow Agent gateway from the cryptographically validated client credential (Set, not Add, so any client-supplied value is overwritten), so it is not client-selectable and carries no cross-org override capability on this route. The orchestrator fails closed with 401 when it is absent or blank; there is no query-string equivalent.

Responses

Response samples

Content type
application/json
{
  • "export": {
    }
}

Delete audit export

Delete an audit export and its associated cloud storage object.

path Parameters
export_id
required
string
header Parameters
X-Org-ID
required
string
Example: travel-us

Organization scope for this request. Stamped by the AxonFlow Agent gateway from the cryptographically validated client credential (Set, not Add, so any client-supplied value is overwritten), so it is not client-selectable and carries no cross-org override capability on this route. The orchestrator fails closed with 401 when it is absent or blank; there is no query-string equivalent.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Process audit export

Trigger processing of a pending audit export. Generates the export file, uploads to cloud storage (if configured), and generates a presigned download URL.

path Parameters
export_id
required
string
header Parameters
X-Org-ID
required
string
Example: travel-us

Organization scope for this request. Stamped by the AxonFlow Agent gateway from the cryptographically validated client credential (Set, not Add, so any client-supplied value is overwritten), so it is not client-selectable and carries no cross-org override capability on this route. The orchestrator fails closed with 401 when it is absent or blank; there is no query-string equivalent.

Responses

Response samples

Content type
application/json
{
  • "export": {
    }
}

List RBI policy templates

List pre-built RBI FREE-AI compliance policy templates.

Responses

EU AI Act

EU AI Act compliance endpoints for technical documentation export, conformity assessments (Article 43), and accuracy/bias tracking (Article 15). Enterprise feature for EU regulatory compliance.

Create compliance export

Creates a new EU AI Act compliance export job for technical documentation (Article 11).

Export types:

  • full_audit: Complete audit trail for regulatory review
  • conformity_evidence: Evidence for conformity assessments
  • hitl_summary: Human-in-the-loop decision summary
  • decision_chain: Full decision chain tracing
  • policy_violations: Policy violation records
  • accuracy_metrics: Model accuracy and bias metrics
header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Request Body schema: application/json
required
export_type
required
string
Enum: "full_audit" "conformity_evidence" "hitl_summary" "decision_chain" "policy_violations" "accuracy_metrics"

Type of compliance export

format
required
string
Enum: "json" "xml" "csv"

Export file format

date_from
string <date-time>

Start of date range

date_to
string <date-time>

End of date range

model_ids
Array of strings

Filter by specific model IDs (optional)

Responses

Request samples

Content type
application/json
{
  • "export_type": "full_audit",
  • "format": "json",
  • "date_from": "2025-01-01T00:00:00Z",
  • "date_to": "2025-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "status": "pending",
  • "export_type": "full_audit",
  • "format": "json",
  • "created_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "date_from": "2019-08-24T14:15:22Z",
  • "date_to": "2019-08-24T14:15:22Z",
  • "download_url": "string",
  • "storage_type": "local",
  • "storage_key": "string",
  • "file_path": "string",
  • "file_size": 0,
  • "record_count": 0,
  • "progress": 0.1,
  • "error_message": "string",
  • "created_by": "string"
}

List exports

List EU AI Act compliance exports for the organization.

query Parameters
limit
integer >= 1
Default: 100

Maximum number of records to return. Defaults vary by endpoint; see per-endpoint description for the cap.

offset
integer >= 0
Default: 0

Number of records to skip from the start of the result set. Pair with limit to walk multi-page reads.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "exports": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Get export status

Get the status of a specific export job.

path Parameters
export_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "status": "pending",
  • "export_type": "full_audit",
  • "format": "json",
  • "created_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "date_from": "2019-08-24T14:15:22Z",
  • "date_to": "2019-08-24T14:15:22Z",
  • "download_url": "string",
  • "storage_type": "local",
  • "storage_key": "string",
  • "file_path": "string",
  • "file_size": 0,
  • "record_count": 0,
  • "progress": 0.1,
  • "error_message": "string",
  • "created_by": "string"
}

Download export

Download a completed export file. When cloud storage is configured, returns a redirect (302) to a presigned URL. For local storage, streams the file.

path Parameters
export_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "file_path": "string",
  • "file_size": 0,
  • "format": "string",
  • "download_url": "string",
  • "storage_type": "local"
}

Create conformity assessment

Create a new EU AI Act conformity assessment (Article 43). Used to document compliance for high-risk AI systems.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Request Body schema: application/json
required
system_id
required
string
system_name
required
string
risk_category
required
string
Enum: "minimal" "limited" "high-risk" "unacceptable"
assessors
Array of strings

Responses

Request samples

Content type
application/json
{
  • "system_id": "ai-system-001",
  • "system_name": "Customer Risk Scoring Model",
  • "risk_category": "high-risk",
  • "assessors": []
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

List conformity assessments

List conformity assessments for the organization.

query Parameters
status
string
Enum: "draft" "in_progress" "submitted" "approved" "rejected"
limit
integer >= 1
Default: 100

Maximum number of records to return. Defaults vary by endpoint; see per-endpoint description for the cap.

offset
integer >= 0
Default: 0

Number of records to skip from the start of the result set. Pair with limit to walk multi-page reads.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "assessments": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Get conformity assessment

Get details of a specific conformity assessment.

path Parameters
assessment_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Update conformity assessment

Update a conformity assessment (only allowed for draft/in_progress status).

path Parameters
assessment_id
required
string
Request Body schema: application/json
required
system_name
string
risk_category
string
Enum: "minimal" "limited" "high-risk" "unacceptable"
assessors
Array of strings
Array of objects (RequirementStatus)
Array of objects (EvidenceItem)
Array of objects (Finding)
object
recommendations
Array of strings

Responses

Request samples

Content type
application/json
{
  • "system_name": "string",
  • "risk_category": "minimal",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Submit assessment for review

Submit a conformity assessment for approval review.

path Parameters
assessment_id
required
string
header Parameters
X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Approve assessment

Approve a submitted conformity assessment.

path Parameters
assessment_id
required
string
header Parameters
X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Request Body schema: application/json
validity_years
integer
Default: 1

Number of years the approval is valid

Responses

Request samples

Content type
application/json
{
  • "validity_years": 1
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Reject assessment

Reject a submitted conformity assessment.

path Parameters
assessment_id
required
string
header Parameters
X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Request Body schema: application/json
required
reason
required
string

Reason for rejection

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "system_id": "string",
  • "system_name": "string",
  • "risk_category": "minimal",
  • "status": "draft",
  • "version": 0,
  • "assessment_date": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "assessors": [
    ],
  • "requirements": [
    ],
  • "evidence": [
    ],
  • "findings": [
    ],
  • "risk_mitigation": { },
  • "recommendations": [
    ],
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitted_by": "string",
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string",
  • "rejected_at": "2019-08-24T14:15:22Z",
  • "rejected_by": "string",
  • "rejection_reason": "string"
}

Get accuracy summary

Get accuracy and bias tracking summary for the organization (Article 15). Provides overview of model performance and compliance status.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "org_id": "string",
  • "total_models": 0,
  • "models_above_target": 0,
  • "models_below_target": 0,
  • "average_accuracy": 0.1,
  • "active_alerts": 0,
  • "last_updated": "2019-08-24T14:15:22Z",
  • "metrics_by_model": { }
}

Record accuracy metric

Record an accuracy metric for a model.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Request Body schema: application/json
required
model_id
required
string
metric_type
required
string
Enum: "accuracy" "precision" "recall" "f1_score" "auc_roc" "auc_pr" "mse" "mae" "custom"
value
required
number <double>
sample_size
integer
window_start
string <date-time>
window_end
string <date-time>
object

Responses

Request samples

Content type
application/json
{
  • "model_id": "model-001",
  • "metric_type": "accuracy",
  • "value": 0.95,
  • "sample_size": 10000
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "model_id": "string",
  • "metric_type": "accuracy",
  • "value": 0.1,
  • "sample_size": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "window_start": "2019-08-24T14:15:22Z",
  • "window_end": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Record bias measurement

Record a bias detection measurement for a model.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Request Body schema: application/json
required
model_id
required
string
category
required
string
Enum: "gender" "age" "ethnicity" "disability" "religion" "nationality" "socioeconomic" "custom"
group_a
required
string

Name of the first comparison group

group_b
required
string

Name of the second comparison group

group_a_rate
required
number <double>

Positive outcome rate for group A

group_b_rate
required
number <double>

Positive outcome rate for group B

sample_size
integer
window_start
string <date-time>
window_end
string <date-time>
object

Responses

Request samples

Content type
application/json
{
  • "model_id": "model-001",
  • "category": "gender",
  • "group_a": "male",
  • "group_b": "female",
  • "group_a_rate": 0.82,
  • "group_b_rate": 0.79,
  • "sample_size": 5000
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "org_id": "string",
  • "model_id": "string",
  • "category": "gender",
  • "score": 0.1,
  • "threshold": 0.1,
  • "is_violation": true,
  • "sample_size": 0,
  • "group_a": "string",
  • "group_b": "string",
  • "group_a_rate": 0.1,
  • "group_b_rate": 0.1,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "window_start": "2019-08-24T14:15:22Z",
  • "window_end": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Get accuracy history

Get historical accuracy metrics for filtering and analysis.

query Parameters
model_id
string
metric_type
string
Enum: "accuracy" "precision" "recall" "f1_score" "auc_roc" "auc_pr" "mse" "mae" "custom"
from
string <date-time>
to
string <date-time>
limit
integer >= 1
Default: 100

Maximum number of records to return. Defaults vary by endpoint; see per-endpoint description for the cap.

offset
integer >= 0
Default: 0

Number of records to skip from the start of the result set. Pair with limit to walk multi-page reads.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "metrics": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Get active alerts

Get active accuracy and bias alerts for the organization.

header Parameters
X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "total": 0
}

Acknowledge alert

Acknowledge an accuracy or bias alert.

path Parameters
alert_id
required
string
header Parameters
X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Responses

Response samples

Content type
application/json
{
  • "status": "acknowledged"
}

Resolve alert

Resolve an accuracy or bias alert.

path Parameters
alert_id
required
string
header Parameters
X-User-ID
string

Caller identity. Defaults to the authenticated user resolved from the request token when omitted. Surface for service-mode callers that proxy on behalf of multiple users.

Responses

Response samples

Content type
application/json
{
  • "status": "resolved"
}

OJK Compliance

OJK AI Governance + UU PDP compliance for Indonesian financial services. Audit export, retention/readiness checks, UU PDP Art. 46 breach-notification lifecycle, and a compliance dashboard. Enterprise feature.

Export OJK audit data

Export audit data for OJK/BI regulatory submission. Supports:

  • Compliance frameworks: OJK_AI_GOVERNANCE, UU_PDP, BI_PJP, OJK_BI_COMBINED (default)
  • Data types: policy_violations, llm_calls, decision_chain, cross_border_transfers, breach_notifications, all (default). hitl_oversight and pii_redactions are accepted by request validation but are not implemented by the export service — requesting them (or expecting them under all) yields no rows and no error (no queryHITLRecords/queryPIIRedactions exists in ojk_audit_export_service.go).
  • Formats: json (default), csv, xml

The date range may span at most 5 years, matching the OJK 5-year (1825-day) retention requirement. The export runs synchronously and returns status: completed with the data inline.

Enterprise Feature: Available only for Indonesian financial services deployments.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Request Body schema: application/json
required
start_date
required
string <date>

Window start (YYYY-MM-DD)

end_date
required
string <date>

Window end (YYYY-MM-DD, not before start_date; range at most 5 years)

format
string
Default: "json"
Enum: "json" "csv" "xml"
framework
string
Default: "OJK_BI_COMBINED"
Enum: "OJK_AI_GOVERNANCE" "UU_PDP" "BI_PJP" "OJK_BI_COMBINED"
data_types
Array of strings
Items Enum: "policy_violations" "llm_calls" "decision_chain" "hitl_oversight" "pii_redactions" "cross_border_transfers" "breach_notifications" "all"

Defaults to [all]

object
include_pii
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "start_date": "2025-01-01",
  • "end_date": "2025-12-31",
  • "format": "json",
  • "framework": "OJK_BI_COMBINED",
  • "data_types": [
    ]
}

Response samples

Content type
application/json
{
  • "export_id": "3f6d2f4e-8f2a-4a1b-9a51-1de1c1b2c3d4",
  • "status": "completed",
  • "framework": "OJK_BI_COMBINED",
  • "format": "json",
  • "summary": {
    },
  • "created_at": "2026-07-10T09:00:00Z",
  • "metadata": {
    }
}

Get OJK export status

Get the status of an OJK audit export by id.

Enterprise Feature.

path Parameters
id
required
string

Export ID from the export request

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Responses

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "status": "string",
  • "framework": "OJK_AI_GOVERNANCE",
  • "format": "json",
  • "summary": {
    },
  • "data": {
    },
  • "download_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    }
}

Get OJK retention status

Reports 5-year (1825-day) retention compliance for OJK audit data. compliance_status is non_compliant when the configured retention is below the 1825-day minimum.

Enterprise Feature.

query Parameters
data_types
string
Example: data_types=policy_violations,llm_calls

Comma-separated list of data types to report on. ⚠️ Parsed but ignored by the current implementation — GetRetentionStatus never reads it and always returns an empty data_types array (ojk_audit_export_service.go).

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Responses

Response samples

Content type
application/json
{
  • "compliance_status": "compliant",
  • "framework": "OJK_BI_COMBINED",
  • "retention_days": 0,
  • "min_retention_days": 1825,
  • "data_types": [
    ],
  • "next_cleanup": "2019-08-24T14:15:22Z"
}

Check OJK compliance readiness

Validates readiness for an OJK regulatory audit across five checks: Data Retention, PII Detection, Human Oversight, Audit Logging, and Breach Notification. Returns a 0-100 score; ready is true at 80+.

Enterprise Feature.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Responses

Response samples

Content type
application/json
{
  • "ready": true,
  • "score": 100,
  • "framework": "OJK_BI_COMBINED",
  • "checks": [
    ]
}

Submit a UU PDP breach notification

Submits a personal-data breach notification per UU PDP Art. 46. The server assigns the id, sets notification_deadline to discovery_time + 72h, defaults notified_authority to MOCDA, and stamps submitted_at. The returned status is normally submitted, or overdue when the 72-hour deadline had already lapsed at submission.

Enterprise Feature.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Request Body schema: application/json
required
id
string

Server-assigned

incident_timestamp
required
string <date-time>
discovery_time
required
string <date-time>
notification_deadline
string <date-time>

Server-computed (discovery_time + 72h)

data_subjects_affected
required
integer >= 1
data_types_involved
required
Array of strings non-empty
description
required
string
remediation_steps
required
Array of strings non-empty
notified_authority
string

Defaults to MOCDA

status
string
Enum: "draft" "submitted" "acknowledged" "overdue" "failed"
submitted_at
string <date-time>
acknowledged_at
string <date-time>
created_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "incident_timestamp": "2026-07-08T14:00:00Z",
  • "discovery_time": "2026-07-09T09:00:00Z",
  • "data_subjects_affected": 1200,
  • "data_types_involved": [
    ],
  • "description": "Misconfigured export bucket exposed customer records",
  • "remediation_steps": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "incident_timestamp": "2019-08-24T14:15:22Z",
  • "discovery_time": "2019-08-24T14:15:22Z",
  • "notification_deadline": "2019-08-24T14:15:22Z",
  • "data_subjects_affected": 1,
  • "data_types_involved": [
    ],
  • "description": "string",
  • "remediation_steps": [
    ],
  • "notified_authority": "string",
  • "status": "draft",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "acknowledged_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Acknowledge a breach notification

Marks a submitted breach notification as acknowledged by the authority. Only the submitted -> acknowledged transition is valid; acknowledging a draft/overdue/failed/already-acknowledged record returns 409.

Enterprise Feature.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Request Body schema: application/json
required
id
required
string

Breach notification id

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "incident_timestamp": "2019-08-24T14:15:22Z",
  • "discovery_time": "2019-08-24T14:15:22Z",
  • "notification_deadline": "2019-08-24T14:15:22Z",
  • "data_subjects_affected": 1,
  • "data_types_involved": [
    ],
  • "description": "string",
  • "remediation_steps": [
    ],
  • "notified_authority": "string",
  • "status": "draft",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "acknowledged_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Sweep lapsed breach-notification deadlines

Flips draft (unsubmitted) breach notifications whose 72-hour UU PDP notification deadline has lapsed to overdue. Intended to be called periodically (deadline sweep).

Enterprise Feature.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Responses

Response samples

Content type
application/json
{
  • "flipped_overdue": 2
}

Get OJK compliance dashboard

Returns the OJK/UU PDP compliance dashboard: compliance score, retention status, breach-notification counts (total and overdue), active policies, and recent violations.

Enterprise Feature.

header Parameters
X-Tenant-ID
string

Tenant identifier. The OJK module falls back to X-Org-ID when absent; a request carrying neither header is rejected with 400 (code missing_tenant).

X-Org-ID
string

Fallback tenant identifier when X-Tenant-ID is absent

Responses

Response samples

Content type
application/json
{
  • "framework": "OJK_BI_COMBINED",
  • "compliance_score": 100,
  • "total_audit_records": 0,
  • "active_policies": 8,
  • "recent_violations": 0,
  • "retention_status": "compliant",
  • "breach_notifications": 3,
  • "overdue_breach_notifications": 0,
  • "last_updated": "2026-07-10T09:00:00Z"
}

Decisions & Overrides

Decision explainability (ADR-043) and session-scoped policy overrides (ADR-044). List recent governance decisions, explain a specific decision, and create/list/revoke time-boxed policy overrides.

Create a session-scoped policy override

Creates a time-boxed override for a static or dynamic policy (ADR-044). A justification (override_reason, max 500 chars) is mandatory. TTL is clamped server-side: default 3600s when omitted, minimum 60s, hard cap 86400s (24h) — the response reports the requested value and the clamp reason when clamping occurred.

Critical-risk policies and policies with allow_override=false cannot be overridden (403).

header Parameters
X-User-Email
required
string

Authenticated user identity (falls back to X-User-ID); missing identity is a 401

X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Request Body schema: application/json
required
policy_id
required
string

Policy UUID, or the human-readable slug (static) / name (dynamic)

policy_type
required
string
Enum: "static" "dynamic"
tool_signature
string

Optional tool scope for the override

override_reason
required
string <= 500 characters

Mandatory justification (ADR-044)

ttl_seconds
integer <int64>

Override lifetime in seconds. Omitted/0 defaults to 3600. Clamped server-side to [60, 86400]; the response reports any clamp.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pii-us-ssn-redact",
  • "policy_type": "static",
  • "tool_signature": "mcp:github/create_issue",
  • "override_reason": "Approved incident-response exception INC-4432",
  • "ttl_seconds": 1800
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "policy_id": "string",
  • "policy_type": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "ttl_seconds": 0,
  • "requested_ttl": 0,
  • "clamped": true,
  • "clamped_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List policy overrides

Lists the tenant's policy overrides, newest first, capped at 100 rows. Revoked overrides are excluded unless include_revoked=true.

Role-scoped reads (#2922): admin/owner list every override in the tenant; every other role lists only the overrides they created (created_by). Revoking an override is scoped the same way. The role/scope is trusted only over the internal proxy-auth channel.

query Parameters
policy_id
string

Filter by policy UUID or slug/name

include_revoked
boolean
Default: false

Include revoked overrides (only the literal true enables it)

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
{
  • "overrides": [
    ],
  • "count": 0
}

Get a policy override

Returns one override by id, tenant-scoped. Another tenant's override returns 404.

path Parameters
id
required
string

Override id

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "policy_id": "string",
  • "policy_type": "string",
  • "tenant_id": "string",
  • "organization_id": "string",
  • "tool_signature": "string",
  • "override_reason": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "revoked_by": "string"
}

Revoke a policy override

Revokes an active override (tenant-scoped). An already-revoked or cross-tenant override returns 404.

path Parameters
id
required
string

Override id

header Parameters
X-User-Email
required
string

Authenticated user identity (falls back to X-User-ID); missing identity is a 401

X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-Org-ID
string
Example: travel-us

Organization identifier. Falls back to authenticated org from the Basic auth client when omitted. Surface for callers that need to override (e.g. cross-org admin reads in Enterprise).

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "revoked_at": "2019-08-24T14:15:22Z"
}

List recent governance decisions

Lists recent decisions for the tenant, newest first. The lookback window and maximum page size are tier-gated: Community/Free sees the last 5 decisions in 24h; Evaluation 100 decisions in 14 days; Enterprise up to 1000 with an unbounded window. Requesting a limit above the tier cap returns 429 with the upgrade envelope (error, limit_type: decision_list_size, tier, limit, remaining, upgrade{tier, wording, compare_url, buy_url}) plus the X-Axonflow-Tier-Limit and X-Axonflow-Upgrade-URL headers. A since earlier than the tier window is silently clamped to the window.

Role-scoped reads (#2922): admin/owner list every user's decisions; every other role lists only their own (rows attributed to their identity). A caller with no resolvable per-user identity gets an empty list. The role/scope is trusted only over the internal proxy-auth channel. DEPLOYMENT_MODE=community lists tenant-wide, and community-saas lists tenant-wide over the agent gateway — see POST /api/v1/audit/search for the single-operator rationale (#3060).

query Parameters
limit
integer >= 1

Page size (positive integer). Defaults to the tier maximum.

since
string <date-time>

RFC3339 lower bound; defaults to (and is clamped to) the tier lookback window

decision
string
Enum: "allowed" "blocked" "redacted" "needs_approval" "error"

Canonical verdict filter

policy_id
string

Filter to decisions where this policy fired

tool_signature
string

Filter by tool signature

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
application/json
{
  • "decisions": [
    ]
}

Explain a governance decision

Returns the explanation for a decision id (ADR-043): matched policies, verdict and reason, risk level, override availability (and any existing override id), the caller's 24h hit count for the first matched policy, and policy version drift (version at decision time vs latest). Tenant-scoped via X-Tenant-ID; a decision belonging to another tenant returns 404 (not 403) so the endpoint is not an existence oracle.

path Parameters
id
required
string

Decision id

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-User-Email
string

Caller identity used for the per-user historical hit count (falls back to X-User-ID)

Responses

Response samples

Content type
application/json
{
  • "decision_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "policy_matches": [
    ],
  • "matched_rules": [
    ],
  • "decision": "string",
  • "reason": "string",
  • "risk_level": "string",
  • "override_available": true,
  • "override_existing_id": "string",
  • "historical_hit_count_session": 0,
  • "policy_source_link": "string",
  • "tool_signature": "string",
  • "policy_version_at_decision": 0,
  • "latest_policy_version": 0,
  • "context": {
    },
  • "context_truncated": true
}

Metrics

Performance monitoring

Get performance metrics (JSON)

Returns comprehensive JSON metrics including:

  • Request counts and rates
  • Latency percentiles (P50, P95, P99)
  • Per-stage timing (dynamic policy, LLM)
  • Per-provider metrics (tokens, cost)
  • Health status

Responses

Response samples

Content type
application/json
{
  • "orchestrator_metrics": {
    },
  • "health": {
    },
  • "providers": {
    },
  • "timestamp": "2025-01-15T10:30:00Z"
}

Prometheus metrics endpoint

Returns metrics in Prometheus exposition format

Responses

Get detailed metrics

Returns detailed metrics from the metrics collector

Responses

Response samples

Content type
application/json
{ }

Decision & Execution Replay

Decision & Execution Replay API for debugging, auditing, and compliance. Captures every step of workflow execution with full input/output snapshots and policy decisions.

List workflow executions

List all workflow executions with optional filtering and pagination. Supports filtering by status, workflow, tenant, time range.

query Parameters
limit
integer
Default: 50

Maximum number of results (default 50)

offset
integer
Default: 0

Pagination offset (default 0)

status
string
Enum: "pending" "running" "completed" "failed"

Filter by execution status

workflow_id
string

Filter by workflow name

start_time
string <date-time>

Filter by start time (RFC3339 format)

end_time
string <date-time>

Filter by end time (RFC3339 format)

header Parameters
X-Tenant-ID
string

Filter by tenant ID

X-Org-ID
string

Filter by organization ID

Responses

Response samples

Content type
application/json
{
  • "executions": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Get execution details

Get full execution details including summary and all steps.

path Parameters
id
required
string

Execution request ID

Responses

Response samples

Content type
application/json
{
  • "summary": {
    },
  • "steps": [
    ]
}

Delete execution

Delete an execution and all its step data.

path Parameters
id
required
string

Execution request ID

Responses

Get execution steps

Get all steps for an execution.

path Parameters
id
required
string

Execution request ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get specific step

Get a specific step by index.

path Parameters
id
required
string

Execution request ID

stepIndex
required
integer

Step index (0-based)

Responses

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "step_index": 0,
  • "step_name": "string",
  • "status": "pending",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "duration_ms": 0,
  • "input": { },
  • "output": { },
  • "provider": "string",
  • "model": "string",
  • "tokens_in": 0,
  • "tokens_out": 0,
  • "cost_usd": 0.1,
  • "policies_checked": [
    ],
  • "policies_triggered": [
    ],
  • "error_message": "string",
  • "retry_count": 0,
  • "approval_required": true,
  • "approved_at": "2019-08-24T14:15:22Z",
  • "approved_by": "string"
}

Get execution timeline

Get a timeline view of execution steps with status indicators.

path Parameters
id
required
string

Execution request ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export execution

Export full execution record for compliance and auditing. Returns a downloadable JSON file.

path Parameters
id
required
string

Execution request ID

query Parameters
format
string
Default: "json"

Export format (default json)

include_input
boolean
Default: true

Include step inputs (default true)

include_output
boolean
Default: true

Include step outputs (default true)

include_policies
boolean
Default: true

Include policy events (default true)

Responses

Response samples

Content type
application/json
{
  • "exported_at": "2019-08-24T14:15:22Z",
  • "format": "string",
  • "execution": {
    }
}

Webhooks

Webhook subscription management for real-time event notifications. Subscribe to events like policy violations, workflow completions, budget alerts, etc.

Create webhook subscription

Create a new webhook subscription to receive real-time event notifications. Events are delivered as HTTP POST requests to the specified URL with HMAC-SHA256 signatures when a secret is provided.

Request Body schema: application/json
required
url
required
string <uri>

URL to receive webhook event payloads

events
required
Array of strings

List of event types to subscribe to. Available events:

  • policy.violation — Policy violation detected
  • policy.created / policy.updated / policy.deleted — Policy lifecycle
  • workflow.completed / workflow.failed / workflow.aborted — Workflow lifecycle
  • workflow.approval_required — Step requires human approval
  • budget.threshold_reached / budget.exceeded / budget.blocked — Budget alerts
  • plan.completed / plan.failed — Plan lifecycle
secret
string

Secret key for HMAC-SHA256 signature verification of webhook payloads

active
boolean
Default: true

Whether the subscription is active

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "wh_abc123",
  • "url": "https://example.com/webhooks/axonflow",
  • "events": [
    ],
  • "active": true,
  • "tenant_id": "tenant-1",
  • "org_id": "org-1",
  • "secret": "whsec_example_placeholder",
  • "created_at": "2026-01-17T10:00:00Z",
  • "updated_at": "2026-01-17T10:00:00Z"
}

List webhook subscriptions

List all webhook subscriptions for the current tenant

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "total": 1
}

Get webhook subscription

Retrieve a specific webhook subscription by ID

path Parameters
id
required
string
Example: wh_abc123

Webhook subscription ID

Responses

Response samples

Content type
application/json
{
  • "id": "wh_abc123",
  • "url": "https://example.com/webhooks/axonflow",
  • "events": [
    ],
  • "active": true,
  • "tenant_id": "tenant-1",
  • "org_id": "org-1",
  • "secret": "whsec_example_placeholder",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update webhook subscription

Update an existing webhook subscription

path Parameters
id
required
string
Example: wh_abc123

Webhook subscription ID

Request Body schema: application/json
required
url
string <uri>

Updated URL to receive webhook event payloads

events
Array of strings

Updated list of event types to subscribe to

active
boolean

Whether the subscription is active

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "wh_abc123",
  • "url": "https://example.com/webhooks/axonflow",
  • "events": [
    ],
  • "active": true,
  • "tenant_id": "tenant-1",
  • "org_id": "org-1",
  • "secret": "whsec_example_placeholder",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete webhook subscription

Delete a webhook subscription. Events will no longer be delivered to this URL.

path Parameters
id
required
string
Example: wh_abc123

Webhook subscription ID

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found"
}

Cost Controls

Budget management and LLM usage tracking for cost optimization. Supports budgets at organization, team, agent, workflow, and user scopes. Provides usage summaries, breakdowns, and pre-request budget checks.

Create a budget

Create a new budget with spending limits. Budgets can be scoped to organization, team, agent, workflow, or user level.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

header Parameters
X-Org-ID
required
string

Organization ID

Request Body schema: application/json
required
id
required
string
name
required
string
scope
required
string
Enum: "organization" "team" "agent" "workflow" "user"
scope_id
string
limit_usd
required
number <double>
period
required
string
Enum: "daily" "weekly" "monthly" "quarterly" "yearly"
on_exceed
string
Default: "warn"
Enum: "warn" "block" "downgrade"
alert_thresholds
Array of integers

Responses

Request samples

Content type
application/json
{
  • "id": "monthly-budget",
  • "name": "Monthly Production Budget",
  • "scope": "organization",
  • "limit_usd": 1000,
  • "period": "monthly",
  • "on_exceed": "warn",
  • "alert_thresholds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "scope": "organization",
  • "scope_id": "string",
  • "limit_usd": 0.1,
  • "period": "daily",
  • "on_exceed": "warn",
  • "alert_thresholds": [
    ],
  • "org_id": "string",
  • "tenant_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List budgets

List all budgets for the organization.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

query Parameters
scope
string
Enum: "organization" "team" "agent" "workflow" "user"

Filter by budget scope

limit
integer
Default: 50

Maximum number of results

offset
integer
Default: 0

Offset for pagination

header Parameters
X-Org-ID
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "budgets": [
    ],
  • "count": 0
}

Get a budget

Get a specific budget by ID.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

path Parameters
id
required
string

Budget ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "scope": "organization",
  • "scope_id": "string",
  • "limit_usd": 0.1,
  • "period": "daily",
  • "on_exceed": "warn",
  • "alert_thresholds": [
    ],
  • "org_id": "string",
  • "tenant_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a budget

Update an existing budget configuration.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

path Parameters
id
required
string

Budget ID

Request Body schema: application/json
required
name
string
limit_usd
number <double>
on_exceed
string
Enum: "warn" "block" "downgrade"
alert_thresholds
Array of integers

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "limit_usd": 0.1,
  • "on_exceed": "warn",
  • "alert_thresholds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "scope": "organization",
  • "scope_id": "string",
  • "limit_usd": 0.1,
  • "period": "daily",
  • "on_exceed": "warn",
  • "alert_thresholds": [
    ],
  • "org_id": "string",
  • "tenant_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a budget

Delete a budget by ID.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

path Parameters
id
required
string

Budget ID

Responses

Get budget status

Get real-time status of a budget including current usage, remaining amount, and whether the budget is exceeded.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

path Parameters
id
required
string

Budget ID

Responses

Response samples

Content type
application/json
{
  • "budget": {
    },
  • "used_usd": 450.25,
  • "remaining_usd": 549.75,
  • "percentage": 45.025,
  • "period_start": "2026-01-01T00:00:00Z",
  • "period_end": "2026-02-01T00:00:00Z",
  • "is_exceeded": false,
  • "is_blocked": false
}

Get budget alerts

Get alerts triggered for a specific budget.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

path Parameters
id
required
string

Budget ID

query Parameters
limit
integer
Default: 50

Maximum number of alerts to return

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "count": 0
}

Check budget before request

Check if a request should be allowed based on budget constraints. Returns whether the request is allowed and the applicable budget status.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

Request Body schema: application/json
required
org_id
required
string
team_id
string
agent_id
string
workflow_id
string
user_id
string

Responses

Request samples

Content type
application/json
{
  • "org_id": "your-org-id",
  • "team_id": "engineering",
  • "agent_id": "support-bot"
}

Response samples

Content type
application/json
Example
{
  • "allowed": true
}

Get usage summary

Get aggregated LLM usage for the current period.

Available in both Community and Enterprise editions. Basic usage overview.

query Parameters
period
string
Default: "monthly"
Enum: "daily" "weekly" "monthly" "quarterly" "yearly"

Time period for aggregation

header Parameters
X-Org-ID
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "total_cost_usd": 450.25,
  • "total_tokens_in": 1250000,
  • "total_tokens_out": 375000,
  • "total_requests": 5420,
  • "average_cost_per_request": 0.083
}

Get usage breakdown

Get usage broken down by a specific dimension.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

query Parameters
group_by
required
string
Enum: "provider" "model" "agent" "team" "user"

Dimension to group by

period
string
Default: "monthly"
Enum: "daily" "weekly" "monthly" "quarterly" "yearly"

Time period for aggregation

header Parameters
X-Org-ID
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "group_by": "provider",
  • "total_cost_usd": 450.25,
  • "items": [
    ]
}

List usage records

List individual usage records with filtering.

Enterprise only. These routes are not registered in Community edition, which returns 404 Not Found.

query Parameters
start_time
string <date-time>

Filter records after this time

end_time
string <date-time>

Filter records before this time

provider
string

Filter by LLM provider

model
string

Filter by model name

agent_id
string

Filter by agent ID

limit
integer
Default: 100

Maximum number of records

offset
integer
Default: 0

Offset for pagination

header Parameters
X-Org-ID
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "records": [
    ],
  • "count": 0,
  • "total": 0
}

Get model pricing

Get pricing information for LLM models.

Available in both Community and Enterprise editions.

query Parameters
provider
string

Filter by provider name

model
string

Filter by model name

Responses

Response samples

Content type
application/json
Example
{
  • "provider": "anthropic",
  • "model": "claude-sonnet-4",
  • "pricing": {
    }
}

Unified Executions

Unified execution tracking and real-time streaming for MAP plans and WCP workflows. SSE streaming provides real-time status updates. Community: 5 concurrent connections per tenant. Enterprise: Unlimited.

List executions (MAP plans + WCP workflows)

Lists unified executions across both MAP plans and WCP workflows, scoped to the tenant/org identified by the X-Tenant-ID and X-Org-ID headers. The page size is capped by the license tier's execution-history limit (at most 100 per page); out-of-range limit or offset values are silently ignored and the defaults used.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Page size (default 20, max 100 or the tier history cap, whichever is lower)

offset
integer >= 0
Default: 0

Number of records to skip

execution_type
string
Enum: "map_plan" "wcp_workflow"

Filter by execution type

status
string
Enum: "pending" "running" "completed" "failed" "cancelled" "aborted" "expired"

Filter by execution status

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-Org-ID
required
string

Organization identifier for scoping results

Responses

Response samples

Content type
application/json
{
  • "executions": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "has_more": true
}

Get unified execution status

Returns the unified status record for a MAP plan or WCP workflow execution. The id is resolved across both subsystems (direct execution id, plan_... plan ids, wf_/wcp_ workflow ids). Requires both X-Tenant-ID and X-Org-ID; a tenant/org mismatch returns 404 (not 403) to avoid a cross-tenant existence oracle.

path Parameters
id
required
string

Execution id (or plan_/wf_/wcp_ prefixed subsystem id)

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-Org-ID
required
string

Organization identifier for scoping results

Responses

Response samples

Content type
application/json
{
  • "execution_id": "string",
  • "execution_type": "map_plan",
  • "name": "string",
  • "source": "string",
  • "status": "pending",
  • "current_step_index": 0,
  • "total_steps": 0,
  • "progress_percent": 0.1,
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "duration": "string",
  • "estimated_cost_usd": 0.1,
  • "actual_cost_usd": 0.1,
  • "steps": [
    ],
  • "error": "string",
  • "tenant_id": "string",
  • "org_id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel a unified execution

Cancels a running MAP plan or WCP workflow through the unified API. The cancellation propagates to the owning subsystem (plan cancel or workflow abort). Cancelling an execution already in a terminal state returns 409.

path Parameters
id
required
string

Execution id (or plan_/wf_/wcp_ prefixed subsystem id)

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

X-Org-ID
required
string

Organization identifier for scoping results

Request Body schema: application/json
optional
reason
string

Cancellation reason (defaults to "cancelled via unified API")

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "execution_id": "string",
  • "execution_type": "map_plan",
  • "name": "string",
  • "source": "string",
  • "status": "pending",
  • "current_step_index": 0,
  • "total_steps": 0,
  • "progress_percent": 0.1,
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "duration": "string",
  • "estimated_cost_usd": 0.1,
  • "actual_cost_usd": 0.1,
  • "steps": [
    ],
  • "error": "string",
  • "tenant_id": "string",
  • "org_id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Stream execution status via SSE

Server-Sent Events stream for real-time execution status updates. Streams events for both MAP plan executions and WCP workflow executions. Community: Limited to 5 concurrent connections per tenant. Enterprise: Unlimited concurrent connections.

path Parameters
id
required
string
header Parameters
X-Tenant-ID
required
string
X-Org-ID
required
string

Organization identifier. Like X-Tenant-ID, required by the unified-execution tenant-ownership check; missing either header is a 401.

Responses

Media Governance

Multimodal image governance for LLM requests. Analyzes images for PII (via OCR), content safety, face/biometric detection, and document classification. Community tier provides fail-open governance with audit trail. Enterprise tier adds configurable enforcement and cloud analyzers.

Get media governance configuration

Returns the media governance configuration for the current tenant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "enabled": true,
  • "allowed_analyzers": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Update media governance configuration

Updates media governance configuration. Enterprise tier only. Community and Evaluation tiers receive a 403 TIER_RESTRICTED response. To toggle system media policies on/off (available to all tiers), use the Dynamic Policy API (/api/v1/dynamic-policies) instead.

Authorizations:
BearerAuth
Request Body schema: application/json
required
enabled
boolean

Enable or disable media governance

allowed_analyzers
Array of strings

Restrict to specific analyzer types

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "allowed_analyzers": [
    ]
}

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "enabled": true,
  • "allowed_analyzers": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Get media governance feature status

Returns the media governance feature availability for the current license tier.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "enabled_by_default": true,
  • "per_tenant_control": true,
  • "tier": "string"
}

Export media governance audit trail (Enterprise)

Exports the media governance audit trail (image analyses, policy actions, block decisions) for the tenant as JSON or CSV.

Enterprise only — non-paid tiers receive 403 (ENTERPRISE_REQUIRED). Tenant scope comes from the X-Tenant-ID header. The export is capped at 10,000 rows, newest first.

query Parameters
from
string <date-time>

Window start (RFC3339). Defaults to 7 days ago.

to
string <date-time>

Window end (RFC3339). Defaults to now.

format
string
Default: "json"
Enum: "json" "csv"

Export format

header Parameters
X-Tenant-ID
required
string
Example: travel-us

Tenant identifier scoping the request. The AxonFlow Agent gateway sets this header after authentication; the orchestrator fails closed when it is absent (401 on audit/decision endpoints, 400 on others — see each operation). Clients cannot widen their scope through it: handlers force the tenant filter from this header, never from the request body.

Responses

Response samples

Content type
{
  • "records": [
    ],
  • "tenant_id": "string",
  • "from": "2019-08-24T14:15:22Z",
  • "to": "2019-08-24T14:15:22Z",
  • "count": 0
}

MAP

List pending approvals (MAP plane)

List steps currently awaiting human approval for MAP-backed workflows — workflows whose metadata carries a plan_id (MAP confirm / step mode). Every returned entry has plan_id populated; this is the intentional asymmetry with the WCP-plane listing at /api/v1/workflows/approvals/pending, mirroring the approve/reject asymmetry established in Issue #1677 / ADR-046.

Reviewer integrators that need to render plan context can read plan_id directly without a second lookup; clients that want a plane-neutral view can use /api/v1/hitl/queue instead.

Available on Evaluation+ licenses (same tier gate as the MAP /steps/{step_id}/approve and /steps/{step_id}/reject endpoints).

query Parameters
plan_id
string

Filter to a single plan_id — returns only steps waiting on that plan.

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

Responses

Response samples

Content type
application/json
{
  • "pending_approvals": [
    ],
  • "count": 1
}

Policy Simulation

Simulate all active policies (Evaluation+)

Runs all active policies against the provided input as a dry run. No audit writes or action application. Requires Evaluation or Enterprise license.

Authorizations:
BearerAuthbasicAuth
Request Body schema: application/json
required
query
required
string

The input text to simulate against all policies

request_type
string

Request type (defaults to "simulation")

object (UserContext)
object (ClientContext)
object

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "request_type": "string",
  • "user": {
    },
  • "client": {
    },
  • "context": { }
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "applied_policies": [
    ],
  • "risk_score": 0,
  • "required_actions": [
    ],
  • "processing_time_ms": 0,
  • "total_policies": 0,
  • "dry_run": true,
  • "simulated_at": "2019-08-24T14:15:22Z",
  • "tier": "string",
  • "daily_usage": {
    }
}

Generate impact report for a policy (Evaluation+)

Tests a single policy against multiple inputs and returns aggregate statistics. Requires Evaluation or Enterprise license.

Authorizations:
BearerAuthbasicAuth
Request Body schema: application/json
required
policy_id
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "policy_id": "string",
  • "inputs": [
    ]
}

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "total_inputs": 0,
  • "matched": 0,
  • "blocked": 0,
  • "match_rate": 0,
  • "block_rate": 0,
  • "results": [
    ],
  • "processing_time_ms": 0,
  • "generated_at": "2019-08-24T14:15:22Z",
  • "tier": "string"
}

Detect policy conflicts (Evaluation+)

Analyzes active policies for contradictions, shadows, and redundancies. Optionally filter to conflicts involving a specific policy. Requires Evaluation or Enterprise license.

Authorizations:
BearerAuthbasicAuth
Request Body schema: application/json
optional
policy_id
string

Optional — filter to conflicts involving this policy

Responses

Request samples

Content type
application/json
{
  • "policy_id": "string"
}

Response samples

Content type
application/json
{
  • "conflicts": [
    ],
  • "total_policies": 0,
  • "conflict_count": 0,
  • "checked_at": "2019-08-24T14:15:22Z",
  • "tier": "string"
}

Evidence Export

Export evidence pack (Evaluation+)

Exports audit logs, workflow steps, and HITL approvals as a bundled JSON pack. Evaluation tier exports include a "NOT FOR REGULATORY SUBMISSION" watermark. Enterprise exports are clean (no watermark).

Authorizations:
BearerAuthbasicAuth
Request Body schema: application/json
required
start_date
required
string

Start date (YYYY-MM-DD or RFC3339)

end_date
string

End date (defaults to now)

types
Array of strings
Items Enum: "audit_logs" "workflow_steps" "hitl_approvals"

Evidence types to include (defaults to all)

limit
integer

Maximum records (capped by tier limit)

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "types": [
    ],
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "tenant_id": "string",
  • "tier": "string",
  • "date_range": {
    },
  • "disclaimer": "string",
  • "record_count": 0,
  • "audit_logs": [
    ],
  • "workflow_steps": [
    ],
  • "hitl_approvals": [
    ],
  • "exported_at": "2019-08-24T14:15:22Z",
  • "daily_usage": {
    }
}

Get evidence summary (Evaluation+)

Returns counts of evidence records by type within the tier's lookback window.

Authorizations:
BearerAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "string",
  • "tier": "string",
  • "window_days": 0,
  • "counts": {
    },
  • "generated_at": "2019-08-24T14:15:22Z",
  • "disclaimer": "string"
}