Compatibility policy

Ironflow is pre-1.0. This page describes the policy that takes effect with 1.0.0. It does not apply to 0.x releases, which can still break callers. See Readiness for current capability levels and version pinning.

From 1.0.0, a 1.x release will not break a caller who uses Ironflow as documented, subject to the exceptions below.

Covered contracts

The promise covers these public contracts.

Contract	What is covered
REST API	Routes, methods, request and response bodies, and query parameters.
ConnectRPC	Public services, methods and messages.
SDKs	Public APIs of the Go SDK, @ironflow/core, @ironflow/node, @ironflow/browser, @ironflow/langgraph, @ironflow/agent and ironflow-py.
Schemas	API request and response shapes, YAML configuration and event envelopes.
CLI	Commands, flags, exit codes and JSON output selected by --output json or IRONFLOW_OUTPUT=json.
Environment variables	Public variable names and their meaning.
Identifiers	The IRN format and API key prefixes, including ifkey_ and ifplatform_.
Webhooks	Payloads and the signature scheme.
Push protocol	HTTP calls from the engine to user functions.
WebSocket	Pubsub frames and close codes.
NATS	Subjects and KV keys visible to users.
Authorization policies	The Rego input document that user policies read.
Errors	REST error shapes and codes. Message text can change.
Metrics	Prometheus metric names and label names. Help text and histogram buckets can change.
MCP	Tool names and required arguments.
Deployment	Docker image tags, ports and data path.
Defaults	Defaults such as port 9123, the meaning of /health and /ready, and documented file locations.
Database	A 1.x binary opens databases written by older 1.x binaries through forward migration. An older binary refuses a newer schema with an error naming its version.
Documented behavior	Guarantees such as step memoization by ID and delivery behavior.

The promise does not cover log line formatting, the dashboard UI, Ironflow Desktop, internal routes, capabilities labeled Evolving or Experimental, or performance numbers. Self-hosted deployment uses the engine container and Docker Compose.

Changes allowed within 1.x

A minor release can add routes, optional fields, flags, environment variables, MCP tools and optional MCP arguments. It can also add enum values. SDKs accept unknown enum values without crashing, either passing them through or mapping them to an unknown value.

Runtime floors can rise in a minor release only when the upstream version reaches end of life. This applies to Go, Node.js, Python, PostgreSQL and supported operating-system and architecture builds. Each increase receives a breaking-change entry in the release notes.

Names inside Ironflow-owned namespaces, such as the ironflow. event prefix, have meanings defined by Ironflow. Minor releases can add names or restrict writes inside these namespaces. Using them for your own data is unsupported. Allowing a write that was previously rejected is not a breaking change.

Exceptions

A correction to a surface that never worked can ship within 1.x. It receives a breaking-change entry and a live test proving the corrected shape.

A security fix can break a working caller when no compatible fix is available. It ships in the next release, which can be a patch release, with a Breaking: Security: entry at the top of the release notes. Ironflow publishes a security advisory in the public release repository or an SDK mirror. The fix is not backported.

Deprecation and removal

A covered contract is not removed during 1.x. Removal waits for 2.0 and requires at least six months of deprecation. The window counts elapsed time, not releases. Migration documentation must exist before the deprecation ships.

Deprecations are signaled on the relevant public paths through REST Deprecation and Sunset headers, protobuf’s deprecated option, TypeScript @deprecated, Go Deprecated:, Python DeprecationWarning, or stderr warnings for CLI flags and environment variables.

SDK and server versions

An older 1.x SDK works with a newer 1.x server. A newer SDK works with an older 1.x server for features that server supports. For newer features, the SDK falls back when possible. Otherwise, it returns an error naming the minimum server version rather than a raw Unimplemented error.

SDKs send their version on every call. Authenticated server responses include X-Ironflow-Version; anonymous responses do not expose the build version.

The engine, CLI and SDKs share a version number. Desktop has its own version line and can remain 0.x after the engine reaches 1.0.

Readiness and support

At 1.0, Ready means covered by this policy. Evolving and Experimental capabilities remain outside the promise. The current pre-1.0 meaning is on the Readiness page.

Ironflow supports only the latest 1.x minor release. Fixes are not backported to older minors. The last 0.x release receives no fixes after 1.0.0.