Skip to main content

Version Compatibility

AxonFlow SDKs and the AxonFlow platform are versioned independently but follow a coordinated release cadence. Each platform release may introduce new API endpoints that require a corresponding SDK update to access. Older SDK versions continue to work with newer platforms -- they simply cannot use the new features.

How Versioning Works​

  • Platform versions (e.g., v4.8.0) represent the server-side AxonFlow Agent and Orchestrator.
  • SDK versions (e.g., v4.3.0) represent the client libraries (Go, Python, TypeScript, Java).
  • SDKs are backward compatible -- an older SDK works against a newer platform for all features the SDK already supports.
  • SDKs are not forward compatible -- a newer SDK calling endpoints that do not exist on an older platform will receive HTTP 404 errors for those specific methods.

Version Discovery​

Starting with platform v4.8.0 and SDK v3.8.0, AxonFlow supports version discovery via the health endpoint. The health response includes a capabilities field that lists which features the running platform supports:

GET /health

{
  "status": "healthy",
  "version": "4.8.0",
  "capabilities": [
    {"name": "health_check", "since": "1.0.0", "description": "Basic health endpoint"},
    {"name": "proxy_llm_call", "since": "1.0.0", "description": "Proxy mode LLM calls with policy enforcement"},
    {"name": "audit_llm_call", "since": "1.0.0", "description": "Audit logging for LLM calls"},
    {"name": "static_policies", "since": "2.0.0", "description": "System policy CRUD"},
    {"name": "gateway_mode", "since": "3.0.0", "description": "Gateway mode integration"},
    {"name": "dynamic_policies", "since": "3.2.0", "description": "Runtime dynamic policy engine"},
    {"name": "multi_agent_planning", "since": "4.3.0", "description": "MAP plan and execute lifecycle"},
    {"name": "workflow_control", "since": "4.3.0", "description": "WCP workflow lifecycle management"},
    {"name": "execution_replay", "since": "4.3.0", "description": "Execution recording and replay"},
    {"name": "cost_controls", "since": "4.4.0", "description": "Budget and cost management"},
    {"name": "media_governance", "since": "4.4.0", "description": "Multimodal image governance"},
    {"name": "wcp_step_metrics", "since": "4.5.0", "description": "WCP step-complete post-execution metrics"},
    {"name": "mcp_check_endpoints", "since": "4.7.0", "description": "Standalone MCP policy check-input/check-output"},
    {"name": "circuit_breaker", "since": "4.7.0", "description": "Circuit breaker pipeline enforcement"},
    {"name": "version_discovery", "since": "4.8.0", "description": "Version and capability discovery"}
  ]
}

SDKs v3.8.0+ use this response to determine which methods are available at runtime, logging a warning if you call a method the platform does not advertise.

Checking Capabilities in Code​

import (
    "context"
    "fmt"
    "log"
    "os"

    axonflow "github.com/getaxonflow/axonflow-sdk-go/v8"
)

client := axonflow.NewClient(axonflow.AxonFlowConfig{
    Endpoint:     os.Getenv("AXONFLOW_ENDPOINT"),
    ClientID:     os.Getenv("AXONFLOW_CLIENT_ID"),
    ClientSecret: os.Getenv("AXONFLOW_CLIENT_SECRET"),
})

health, err := client.HealthCheckDetailed()
if err != nil {
    log.Fatalf("Health check failed: %v", err)
}

fmt.Printf("Platform version: %s\n", health.Version)

if health.HasCapability("mcp_check_endpoints") {
    // Safe to call MCPCheckInput / MCPCheckOutput
    result, err := client.MCPCheckInput(context.Background(), axonflow.MCPCheckInputRequest{
        ConnectorType: "postgres-prod",
        Statement:     userInput,
    })
    // ...
} else {
    fmt.Println("MCP policy check not available on this platform version")
}

Compatibility Matrix​

The table below shows which SDK version is required for features introduced in each platform release.

Platform VersionMinimum SDK VersionFeatures Added
v7.9.0Go v8.0.0, Python v8.0.0, TypeScript v8.0.0, Java v8.0.0, Rust v0.2.0 (preview). The v8 stable-SDK train removes the programmatic telemetry: false config field — AXONFLOW_TELEMETRY=off is now the sole opt-out across all five SDKs (one mental model, no library-side backdoor). Rust v0.2.0 has a broader scope than the stable train: the new client.list_decisions(opts) decision-history API, an Anthropic interceptor (joining the existing OpenAI interceptor), central-checkpoint telemetry parity (heartbeat now routes through https://checkpoint.getaxonflow.com/v1/ping for the first time, bringing Rust into adoption-analytics parity with the four stable SDKs), an AxonFlowConfig::sandbox(...) convenience constructor for cross-SDK parity, and a URL-encoding fix that aligns path-parameter percent-encoding with the other SDKs.Decision-record + observability release: new GET /api/v1/decisions list endpoint with tier-aware caps (Free 24h × 5; Pro 30d × 100; Self-hosted Evaluation 14d × 100; Self-hosted Enterprise full retention × 1000); list_recent_decisions MCP tool wraps the same endpoint inline for any host CLI; policy_version_at_decision field on the /explain payload for compliance drill-in; anonymous platform-level startup heartbeat (agent + orchestrator) closing the visibility gap for docker compose up deployments that never instantiate a language SDK; v1 telemetry-receiver schema additions (telemetry_type, component, license_tier, environment_class, stream) with closed-enum normalization; Rust joins the language-SDK allowlist on the receiver. Privacy improvements on the central telemetry pipeline — salted SHA-256 source-IP hashing (was bare SHA-256), and 90-day operational-log source-IP retention disclosed explicitly. Fixed: Community SaaS daily-cap 429 events now persist with full attribution.
v7.4.5Go v6.0.0 (BREAKING — SDKCompatibility.MinSDKVersion and RecommendedSDKVersion change from string to map[string]string to match the actual on-the-wire shape; new MinSDKVersionFor("go") / RecommendedSDKVersionFor("go") helpers; the Go module path moves to github.com/getaxonflow/axonflow-sdk-go/v6), Python v6.9.0, TS v6.2.0, Java v6.2.0. All four SDKs gain LLM-provider listing: ListProviders / list_providers / listProviders / listLLMProviders plus …Paged (single-page with metadata) and listAll… (auto-paginates) variants; LLMProvider now carries endpoint, model, region, rate_limit, timeout_seconds, settings alongside the existing health snapshot. TypeScript and Go Sandbox() defaults retargeted from the decommissioned staging-eu.getaxonflow.com to http://localhost:8080; production callers always pass an explicit endpoint and are unaffected.Platform patch: org_id now propagates end-to-end through executePlanHandler and executeWorkflowHandler into workflow_engine.StartExecution, so /api/v1/executions returns rows for new MAP plan executions instead of dropping them on the org-scoped read filter. Existing rows keep org_id="" and remain invisible — no backfill in this patch. The SDK release train ships alongside: Go cuts a major for the SDKCompatibility wire-shape fix that has been a silent no-op since v4.8.0 (the string field unmarshalled the JSON object to an empty string, making the SDK version-mismatch warning a no-op); Python / TS / Java ship as additive minors. The new listProviders() family closes the parity gap so all four SDKs can introspect provider configuration and per-provider health without resorting to /health body parsing. The six previously-dropped fields on LLMProvider (endpoint through settings) are pure additions — older platforms return zero values; SDK callers should treat absence as "platform did not populate" rather than an error.
v7.4.4Go v5.8.0, Python v6.8.0, TS v6.1.0, Java v6.1.0 (same SDK train as v7.4.3; v7.4.4 is a platform-only patch).Documentation-grade OpenAPI correction: splits CreateOverrideResponse from the at-rest PolicyOverride schema, matching what the platform server has been emitting all along. Mirrors the CreateWorkflowResponse precedent — create-time TTL clamping fields (ttl_seconds, requested_ttl, clamped, clamped_reason, expires_at) split from at-rest concerns (action_override, enabled_override, tool_signature). Hand-written SDKs / plugins unaffected; relevant only to code-generated clients.
v7.4.3Go v5.8.0, Python v6.8.0, TS v6.1.0, Java v6.1.0 (additive Plugin Batch 1 fields). The new SDK versions surface on mcpCheckInput / mcpCheckOutput (snake_case wire shape): decision_id, risk_level (low|medium|high|critical), policy_matches: ExplainPolicy[], override_available, override_existing_id on the input response; decision_id, policy_matches, redacted_message on the output response.Documentation-grade platform patch: two MCP-response spec corrections — MCPCheckInputResponse gains 5 fields and MCPCheckOutputResponse gains 3, all of which the agent has emitted since v7.1.0 (Plugin Batch 1) but the spec hadn't documented. Three new explainability schemas added (ExplainPolicy, ExplainRule, DecisionExplanation). The four AxonFlow plugins (OpenClaw, Claude Code, Cursor, Codex) clear most of their wire-shape contract gate baseline drift on the next regen against this spec SHA. Hand-written SDKs and plugins unaffected; relevant only to code-generated clients.
v7.4.2Go v5.7.0, Python v6.7.0, TS v6.0.0 (BREAKING — PolicyInfo ↔ MCPPolicyInfo renamed; legacy names preserved as @deprecated aliases for one major), Java v6.0.0 (BREAKING — WebhookSubscription.equals() / hashCode() now identity-based on id).Documentation-grade platform patch: two OpenAPI spec corrections — AISystemRegistry.materiality → materiality_classification in masfeat-api.yaml, and DynamicPolicyInfo reduced from 8 aspirational fields to the 4 actual server fields (policies_evaluated, matched_policies, orchestrator_reachable, processing_time_ms) in agent-api.yaml. Hand-written SDKs unaffected; relevant only to code-generated clients. v6 SDK alignment cycle landed on the same day: TS / Java cut a major for breaking changes; Python (v6.7.0) and Go (v5.7.0) ship as additive minors. All four SDKs gain a wire-shape contract gate that pins SDK type annotations against the OpenAPI spec SHA, plus the audit-driven additive sweep (WebhookSubscription.secret, StepGateRequest.tokens_in/out/cost_usd, StepGateResponse.decision_id, pagination echoes, ownership scoping on Budget, wire-canonical UsageRecord fields, and ~15 more).
v7.4.1Go v5.6.0, Python v6.6.0, TS v5.6.0, Java v5.7.0 (same SDK train as v7.4.0; v7.4.1 is a platform-only patch).Portal HITL + audit trail visibility patch: /api/v1/audit/summary returns six new card-view aggregates (total_requests, allowed_requests, blocked_requests, modified_requests, block_rate_percent, avg_latency_ms); Compliance Summary arithmetic always closes (Total = Allowed + Blocked + Modified); unified execution step now distinguishes approver from rejector via rejected_by / rejected_at fields; WCP step approve / reject and HITL queue approve / reject now emit audit_logs rows; rejections propagate aborted status to the unified execution tracker; historical workflows decided pre-patch reconcile their terminal approval state on read; portal sidebar approvals badge refreshes immediately on approve / reject via approvals:updated CustomEvent.
v7.4.0Go v5.6.0, Python v6.6.0, TS v5.6.0, Java v5.7.0. The new versions expose the unified rich ApproveStepResponse / RejectStepResponse shape (decision, retry_context, approval_id, approved_by/at or rejected_by/at, policies_matched) on both WCP and MAP planes plus the new pending-list method (getPendingPlanApprovals / get_pending_plan_approvals / GetPendingPlanApprovals) with a plan_id filter. Three pre-existing URL bugs fixed: WCP approve / reject / list now hit /api/v1/workflows/... instead of the non-existent /api/v1/workflow-control/... paths. SDK signatures of approveStep / rejectStep now take a comment / reason as the third argument (audit-comment was always required server-side; pre-v7.4.0 SDK calls silently sent an empty body and got 400).HITL response parity: WCP and MAP step approve / reject endpoints now return a unified shape (POST /api/v1/workflows/{id}/steps/{step_id}/approve|reject and POST /api/v1/plans/{id}/steps/{step_id}/approve|reject); MAP plane-scoped approve / reject lowered from Enterprise-only to Evaluation+; new MAP plane-scoped pending listing GET /api/v1/plans/approvals/pending (with optional ?plan_id= filter) at the same Evaluation+ tier. Reviewer tools now hit identical tier gates and identical response shapes regardless of which plane the workflow runs on. CI contract test locks the two responses together so any field added to the response shape surfaces on both planes by default.
v7.3.0Go v5.5.0, Python v6.5.0, TS v5.5.0, Java v5.6.0. Every SDK exposes the retry_context model on StepGateResponse and a typed IdempotencyKeyMismatch error (*IdempotencyKeyMismatchError in Go, IdempotencyKeyMismatchError in TS / Python, IdempotencyKeyMismatchException in Java).Community: retry_context block on every StepGateResponse (always present, including first call) — fields gate_count, completion_count, prior_completion_status (enum none / completed / gated_not_completed), prior_output_available, prior_output, prior_completion_at, first_attempt_at, last_attempt_at, last_decision, idempotency_key; replaces the ambiguous cached: bool which stays populated but is deprecated. ?include_prior_output=true opt-in on /gate so agents can recover the prior /complete payload. Caller-supplied idempotency_key on /gate and /complete (max 255 chars), immutable once set; mismatch returns HTTP 409 IDEMPOTENCY_KEY_MISMATCH with structured error envelope (workflow_id, step_id, expected_idempotency_key, received_idempotency_key). MarkStepCompleted HTTP handler now reads tenant identity from X-Tenant-ID consistently with StepGate. Evaluation: retry-aware dynamic policy condition fields — step.gate_count, step.completion_count, step.prior_completion_status, step.prior_output_available, step.last_decision, step.first_attempt_age_seconds, step.idempotency_key. Tier gate enforced at policy create, update, and bulk-import paths: Community licenses receive HTTP 403 FEATURE_REQUIRES_EVALUATION_LICENSE on any policy referencing step.* fields. UX note: retry-aware policies fire only when callers pass retry_policy: "reevaluate" on subsequent gate calls; default idempotent retries hit the cache and bypass the policy engine (see the Evaluation example in examples/wcp-retry-idempotency/evaluation/ for the three-gate walkthrough). Two additive migrations (071 + 072); no breaking changes.
v7.2.0Go v5.4.0, Python v6.4.0, TS v5.4.0, Java v5.5.0 (adds mapTimeout on AxonFlowConfig.builder() for SDK parity with TS / Python / Go).The Bug Bash Bonanza: tenant-scope fail-closed enforcement across tenant-scoped endpoints (evidence export/summary, decisions explain, policy simulate/impact-report, cost estimate, plan cost, audit search/tenant); new structured TENANT_REQUIRED (401) error code on the evidence, simulate, and cost families when X-Tenant-ID is missing; new orchestrator env AXONFLOW_MAP_MAX_TIMEOUT_SECONDS (default 300s, clamped 60..1800s) so MAP plans can run the full plan budget without the orchestrator cutting the connection; agent /health response now includes a validated tier field; agent proxies /api/v1/euaiact/* so the EU AI Act module is reachable through the single entry point; canonical /api/v1/policy-overrides GET alias matches the policy-categories / static-policies / dynamic-policies naming pattern; PUT /api/v1/policies/{id} accepts the context_aware policy type (used by Tenant Isolation, Debug Mode Restriction, and Sensitive Data Control system policies); POST /api/v1/policies/{id}/overrides accepts require_approval (HITL) as a terminal override action alongside block, redact, warn, log; GET /api/v1/policies honours the tier and category query params; legacy snake-case policy IDs like tenant_isolation and sensitive_data_control are now accepted by per-policy endpoints.
v7.1.1Go v5.4.0, Python v6.4.0, TS v5.4.0, Java v5.4.0. Plugin versions: OpenClaw v1.3.1 (adds X-User-Email forwarding required by createOverride / revokeOverride / listOverrides; v1.3.0 clients get 401 on those endpoints), Claude Code v0.5.1, Cursor v0.5.1, Codex v0.4.1 (all three are code-identical to v0.5.0 / v0.5.0 / v0.5.0; patch bump only adds an install-and-use smoke E2E, users on earlier versions against platform v7.1.1 still get the full richer-context block shape automatically).Plugin Batch 1 patch release: richer block context (decision_id, risk_level, policy_matches, override_available, override_existing_id) now returned on every block from both the /api/v1/mcp/check-input HTTP endpoint and the MCP server's check_policy / check_output JSON-RPC tools; explainDecision(id) resolves MCP-path decisions; createOverride / listOverrides accept either the UUID or the human-readable slug/name for policy_id; session overrides apply on the MCP check paths (not just WCP step-gate); audit-filter search tolerates NULL scan targets. No new features; these close ten shipped gaps in v7.1.0 surfaced across two rounds of post-release install-and-use E2E (six HTTP-path gaps via OpenClaw, four additional MCP-tool-path gaps via Claude Code / Cursor / Codex).
v7.1.0Go v5.4.0, Python v6.4.0, TS v5.4.0, Java v5.4.0Plugin Batch 1: execution boundary semantics (RetryPolicy idempotent/reevaluate, cached/decision_source fields), workflow checkpoints (Evaluation+ / Enterprise), risk-tiered HITL approval routing, governed session overrides with TTL + mandatory justification, explain-on-demand endpoint (GET /api/v1/decisions/:id/explain), and audit search filter parity (decision_id, policy_name, override_id)
v7.0.1Go v5.3.1 (recommended for auth fixes), Python v6.0.0, TS v5.0.0, Java v5.0.0Patch release: unified auth across gateway/MCP/proxy, community-saas telemetry tracking, audit identity hardening. Go SDK v5.3.1 fixes missing auth headers on ListConnectors, GetConnector, GetConnectorHealth, GetPlanStatus, and all execution replay methods
v7.0.0Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0Governance profiles (AXONFLOW_PROFILE, AXONFLOW_ENFORCE), relaxed default detection actions, SDK telemetry endpoint_type field (SDKs v5.3.0 / v6.3.0), checkpoint retention bumped 90→180 days
v6.1.0Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0Mistral LLM provider, GovernedTool adapter (TS/Go/Java), checkToolInput/checkToolOutput aliases, Cursor/Codex integration
v6.0.0Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0X-Tenant-ID removed, auth required in eval/enterprise, proxied enterprise endpoints, PlanResponse status field
v4.8.0v3.8.0Version discovery, capability registry
v4.7.0v3.7.0MCP standalone policy-check endpoints (check-input, check-output), circuit breaker pipeline wiring
v4.5.0v3.6.0WCP step-complete post-execution metrics (tokens, cost, output)
v4.4.0v3.5.0Media governance (multimodal image analysis), cost controls, budget enforcement
v4.3.0v3.4.0Multi-Agent Planning (MAP), Workflow Control Plane (WCP), execution replay, failWorkflow(), HITL queue API
v4.0.0v3.0.0Client credentials authentication (OAuth2-style client_id + client_secret)
tip

All SDKs maintain backward compatibility within the v3.x line. Upgrading from v3.4.0 to v3.8.0 requires no code changes -- new methods are additive only.

Upgrade Recommendations​

Keep SDKs Within One Minor Version of the Platform​

For the best experience, keep your SDK version no more than one minor version behind the platform. For example, if your platform is v6.0.0, use the v5.0.0/v6.0.0 SDK releases.

Upgrade Path​

  1. Check your current platform version by calling the health endpoint: GET /health
  2. Review the compatibility matrix above to see which features you are missing.
  3. Update your SDK dependency:
go get github.com/getaxonflow/axonflow-sdk-go/v8@latest
  1. Test in staging before rolling out to production.
  2. No code changes required -- new SDK versions are drop-in replacements.

Platform Upgrade Without SDK Upgrade​

If you upgrade the platform but keep an older SDK:

  • All existing SDK methods continue to work normally.
  • New platform features are simply not accessible from the SDK.
  • No errors are raised -- the SDK does not call endpoints it does not know about.

For many production teams, this is the safest rollout order: upgrade the platform first, verify health, policy behavior, and dashboards, then let application teams adopt newer SDK methods on their own schedule.

SDK Upgrade Without Platform Upgrade​

If you upgrade the SDK but keep an older platform:

  • All existing methods continue to work normally.
  • Calling new SDK methods that map to endpoints not present on the older platform will return HTTP 404 errors.
  • SDK v3.8.0+ logs a warning when the health endpoint reports missing capabilities, so you can catch this early.

This is where capability discovery becomes especially valuable. It lets one service start checking for newer MCP, orchestration, or governance features without assuming every environment is already on the latest platform release.

What Teams Usually Validate During Upgrades​

Before rolling a new SDK or platform version across environments, the most useful checks are:

  1. confirm the platform version and capability list from GET /health
  2. verify auth mode, tenant headers, and deployment mode are unchanged
  3. run one MCP flow and one orchestration flow in staging
  4. confirm dashboards, audits, and policy decisions still look normal
  5. only then enable newly introduced SDK methods or API surfaces

FAQ​

What happens if I upgrade the SDK without upgrading the platform?​

Existing features continue to work. New methods added in the SDK update will return HTTP 404 if the platform does not have the corresponding endpoints. Starting with SDK v3.8.0, the SDK checks the platform's capability list at initialization and logs a warning for any methods that may not be available.

What happens if I upgrade the platform without upgrading the SDK?​

Nothing breaks. Your SDK continues to work with all the features it already supports. You simply will not have access to the new platform features until you also upgrade the SDK.

Can I run different SDK versions across services?​

Yes. Each service can use its own SDK version independently. The platform handles requests from any supported SDK version. This is common during gradual rollouts where you upgrade one service at a time.

Is there a minimum platform version for any SDK version?​

SDK v5.0.0 (Go/TS/Java) and v6.0.0 (Python) require platform v6.0.0 or later. Earlier SDK v3.x/v4.x versions work with platform v4.x/v5.x releases.

How do I check which platform version I am running?​

Call the health endpoint directly:

curl https://your-axonflow-endpoint/health

Or use the SDK:

health = await client.health_check_detailed()
print(health.version)
Last updated on