Versioning & Deprecation

Current Version

The current major version is 1. Every API response — REST API (/api/*), Agent API (/agent/*), and MCP endpoint (/mcp) — carries an X-API-Version header:

HTTP/1.1 200 OK
Content-Type: application/json
X-API-Version: 1

What Changes Without a Version Bump

Additive changes ship continuously and are always backwards-compatible. Your integration must tolerate:

• New endpoints and new HTTP methods on existing paths
• New optional request fields and query parameters
• New fields in response bodies (parse what you need, ignore the rest)
• New values in open-ended enums (e.g. new regions, OS templates, or resource states)
• New response headers

The published OpenAPI specification is regenerated with every release and its info.version follows semver: minor bumps are additive, major bumps are breaking.

What Counts as Breaking

• Removing or renaming an endpoint, request field, or response field
• Making an optional field required, or changing a field's type
• Changing the meaning of an existing value or error code
• Tightening validation in a way that rejects previously valid requests

Deprecation Process

Breaking changes ship under a new URL prefix (e.g. /agent/v2/) and the old surface keeps working during a migration window of at least 6 months. During that window, responses from the deprecated surface carry:

HTTP/1.1 200 OK
Content-Type: application/json
X-API-Version: 1
Deprecation: true
Sunset: Sat, 27 Feb 2027 00:00:00 GMT
Link: <https://edge.network/docs/api/versioning>; rel="deprecation"

Deprecations are also announced in the changelog and by email to affected accounts. Nothing is ever removed silently.