---
title: Versioning & Deprecation
description: What can change in the v1 API without notice, what counts as breaking, and how deprecations are announced.
source: https://www.edgaze.ai/docs/api/versioning
section: api
---
# Versioning & Deprecation

> What can change in the v1 API without notice, what counts as breaking, and how deprecations are announced.

The REST API is versioned in the URL: every endpoint lives under `https://api.edgaze.ai/v1`. Within v1, Edgaze only makes changes that keep working integrations working. Changes that would break one are not made.

**Audience: Developers and SDK authors who need to know what will stay stable.**

## Changes that can happen at any time

These are not breaking. Build your client to tolerate them:

- New endpoints, and new optional query parameters, headers, or body fields.
- New fields in response bodies, event `data`, and webhook bodies.
- New values in open sets: run event types, `activity.kind`, SSE `event` names, webhook event types, and error codes. Ignore a value you do not recognize, and handle an unknown error code like any other error with the same HTTP status.
- New response headers, and new HTTP statuses that an existing endpoint documents in the OpenAPI document.
- Changes to human-readable text, such as error `message` values and descriptions. Branch on `error.code`, never on `message`.
- Higher limits, for example a larger maximum page size.

## Changes that are breaking

These never happen within v1:

- Removing or renaming an endpoint, field, parameter, header, or enum value.
- Changing a field's type or meaning, or making an optional field required in a request.
- Returning a different error code or HTTP status for a condition that already had one.
- Requiring a scope that an endpoint did not require before.
- Lowering a documented limit that a working integration could already rely on.

## How deprecations are announced

When something in v1 is superseded, it is deprecated, not removed:

- The OpenAPI document marks it `deprecated: true`, and its docs page says what to use instead.
- The [changelog](/docs/changelog) announces it.
- Responses that used the deprecated feature carry a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) with the date it was deprecated, for example `Deprecation: @1786492800`, and a `Link` header with `rel="deprecation"` pointing at this page.

A deprecated v1 feature keeps working for as long as v1 is served.

## The OpenAPI document's version

`info.version` in the [OpenAPI document](/docs/api/openapi) follows semantic versioning within v1: the minor version goes up when something is added, and the patch version for corrections to the document itself. The major version stays at 1 for as long as the API path is `/v1`. Each version is published to the `edgaze-ai/edgaze-openapi` repository, so you can pin one.

## Currently deprecated

| What                                | Since      | Use instead |
| ----------------------------------- | ---------- | ----------- |
| `workflowId` in the POST /runs body | 2026-08-12 | `workflow`  |