---
title: "API Versioning"
description: "Our versioning policy: how we evolve APIs over time without breaking your integration."
url: "https://education.gough.run/guides/publish-apis/versioning"
image: "https://education.gough.run/_og/d/c_Ocean.takumi,title_API+Versioning,description_~T3VyIHZlcnNpb25pbmcgcG9saWN5OiBob3cgd2UgZXZvbHZlIEFQSXMgb3ZlciB0aW1lIHdpdGhvdXQgYnJlYWtpbmcgeW91ciBpbnRlZ3JhdGlvbi4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiM2NmFhMjMifX19,p_Ii9ndWlkZXMvcHVibGlzaC1hcGlzL3ZlcnNpb25pbmci,s_PFT68h1wCt3fyWtV.png"
---

## API Versioning

Our versioning policy: how we evolve APIs over time without breaking your integration.

## [Our promise](#our-promise)

We don't break integrations without warning. APIs evolve — new features get added, mistakes get corrected — but we follow strict rules about what counts as a breaking change and how breaking changes are introduced.

This page covers:

-   What we consider backward-compatible (we add these freely)
-   What we consider breaking (we introduce these as new versions)
-   How long previous versions remain supported
-   How to detect schema changes before they affect your integration

## Explore our APIs

Connect, create, and innovate with our easy-to-use APIs.

[Start building](https://education.gough.run/apis)

### [Versioning by API type](#versioning-by-api-type)

| API Type | Versioning approach                                                              |
| :------- | :------------------------------------------------------------------------------- |
| REST     | URL-based: /stats/v1, /stats/v2 running in parallel                              |
| GraphQL  | Endpoint-based: /graphql, /graphql/v2. Schema additions are backward-compatible within a major version |
| MCP      | Tool-set versioned independently. tools/list reflects the current available set  |

### [What's a breaking change](#whats-a-breaking-change)

A change is breaking if existing well-formed integrations could stop working after the change. Examples:

-   Removing a field from a response
-   Renaming a field or operation
-   Changing the type of a field (e.g. string to integer)
-   Removing an enum value
-   Adding a required request parameter
-   Changing authentication or authorisation semantics
-   Reducing the maximum value of a numeric range

Any of these will only happen in a new major version (e.g. `v2`).

### [What's not a breaking change](#whats-not-a-breaking-change)

Backward-compatible additions can be made to the current version at any time, without prior notice:

-   Adding a new optional request parameter
-   Adding a new field to a response
-   Adding a new enum value
-   Adding a new operation or endpoint
-   Adding a new error code variant (existing handling for unknown errors should still work)
-   Performance improvements that don't change wire behaviour

We recommend designing your integration to ignore unknown fields and unknown enum values gracefully — this lets you benefit from new fields without code changes on your side.

### [Version lifecycle](#version-lifecycle)

When we introduce a new major version (e.g. `v2`):

1.  Both `v1` and `v2` run in parallel for at least **6 months**
2.  We send deprecation notifications through email and a banner in this portal at 6, 3, and 1 month marks
3.  After the deprecation period, `v1` returns a `410 Gone` for new requests and is eventually removed

You're encouraged but not required to migrate to the latest version. As long as a version is still supported, you can continue to use it.

### [Detecting schema changes](#detecting-schema-changes)

For machine-checkable change detection, integrate one of these into your CI pipeline:

```bash
# REST: pull the OpenAPI spec
curl https://api.example.com/stats/v1/openapi.yaml -o latest.yaml
diff prev.yaml latest.yaml

# GraphQL: introspect the schema
curl https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name fields { name } } } }"}' \
  > latest-schema.json
diff prev-schema.json latest-schema.json

# MCP: list available tools
curl https://api.example.com/mcp/stats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
  > latest-tools.json
```

If you see additions, no action needed. If you see removals, that means we've started a deprecation cycle — check your email for the notification and your deprecation timeline.

## [Quick reference](#quick-reference)

| Change                 | Treatment                                        |
| :--------------------- | :----------------------------------------------- |
| Add field to response  | Backward-compatible; goes in current version     |
| Add optional parameter | Backward-compatible; goes in current version     |
| Add enum value         | Backward-compatible; goes in current version     |
| Add operation          | Backward-compatible; goes in current version     |
| Remove field           | Breaking; new major version, 6 month deprecation |
| Rename anything        | Breaking; new major version, 6 month deprecation |
| Change type            | Breaking; new major version, 6 month deprecation |
| Change auth semantics  | Breaking; new major version, 6 month deprecation |

If you're unsure about a specific change you've seen and whether it should be considered breaking, contact our partner support channel.