---
title: "Versioning & deprecation"
description: "Edge Network API versioning and deprecation policy: what counts as a breaking change, how deprecations are signalled, and how much notice integrations get."
url: "https://edge.network/docs/api/versioning"
section: "REST API"
---

# Versioning & deprecation

The Edge Network API is versioned so agents and integrations can rely on a stable surface. This page is the policy: what we consider a breaking change, how we signal one, and how much notice you get.

## 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
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](/openapi.json) 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
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"
```

| Header | Meaning |
|---|---|
| `Deprecation` | This surface is deprecated. Plan your migration. |
| `Sunset` | The date the surface stops working ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). Always ≥ 6 months out. |
| `Link` (`rel="deprecation"`) | Migration guide for the specific change |

Deprecations are also announced in the [changelog](/releases) 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`](/openapi.json) to discover new capabilities. Additive changes appear there first.