---
title: "Versioning & Deprecation"
description: "Edge Network API versioning strategy and deprecation policy — how we signal changes so integrations never break without warning."
url: https://edge.network/docs/api/versioning/
---

# Versioning & Deprecation

# 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 — 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](https://edge.network/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/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](https://edge.network/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](https://edge.network/openapi.json) to discover new capabilities — additive changes appear there first.

[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)