Contract and resource versioning
Path-based API versioning (/v1), the x-grid82-api-version header, deprecation headers, and immutable page and workflow versions.
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 (
deprecatedin OpenAPI,DeprecationandLinkHTTP headers, and aSunsetheader 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:
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.