---
title: "Contract and resource versioning"
description: "Path-based API versioning (/v1), the x-grid82-api-version header, deprecation headers, and immutable page and workflow versions."
canonical: "https://grid82.com/docs/developers/rest/versioning"
updated: "2026-11-20"
---

# Contract and resource versioning

## REST API versioning

All Grid82 REST routes live under `/v1`. Every response carries the exact contract version in the `x-grid82-api-version` header, matching `info.version` in the OpenAPI documents.

- **Additive changes stay under `/v1`.** New endpoints, optional request parameters, and additional response keys ship without changing base paths. Ensure clients ignore unrecognized response keys.
- **No silent operation renames.** Because operation IDs drive MCP tool names and CLI subcommands, renames go through formal deprecation (`deprecated` in OpenAPI, `Deprecation` and `Link` HTTP headers, and a `Sunset` header once scheduled for removal).
- **Breaking contract changes.** Coordinated breaking changes across many routes will increment the path prefix to `/v2`.

## Immutable Interface page versions

Every time a builder or user saves an Interface page (`pages.codeSet` / `my.pages.codeSet`), Grid82 compiles the TSX code and creates a new immutable version number. Publishing simply updates the live version pointer:

```http
GET  /v1/apps/{appId}/pages/{pageId}/versions
POST /v1/apps/{appId}/pages/{pageId}/publish   {"version": 4}
```

Users with a page already open finish their session on the version they loaded; rolling back points the app back to an earlier compiled version with zero rebuild delay.

## Workflow version pins

Saving workflow source (`workflows.codeSet`) creates a new version, while live triggers remain on the currently activated version until you activate the new one. Runs already asleep on `step.sleep` or `approval.ask` finish on the version that started them.
