Versioning & deprecation

Current version#

The current major version is 1. Every API response from the 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.

Guidance for agents#

• Read X-API-Version once per session; alert your operator if it changes unexpectedly.
• Treat a Deprecation or Sunset header as a signal to surface a migration task, not an error.
• Re-fetch /openapi.json to discover new capabilities. Additive changes appear there first.