---
title: "API & contract stability"
description: "What is stable today, what can still change, and the compatibility posture Guuey's public contracts take at launch."
---

<!-- launch-flip: rewrite-or-delete at GA -->

:::caution[Early preview]
Guuey is in early preview. Until launch, public surfaces can still change
with the product — including breaking changes without a deprecation
window. Pin exact `@guuey/*` package versions and expect to update.
:::

## What is versioned today

Some contracts already carry explicit versioning, preview or not:

- **`guuey.json` is schema-versioned.** The root `"schema"` field is a
  decimal integer string (currently `"1"`), bumped only on a change an
  older reader cannot interpret correctly. A document declaring a newer
  schema is refused everywhere — the CLI says `SCHEMA_TOO_NEW` (upgrade
  `@guuey/cli`), the API answers `400 SCHEMA_UNSUPPORTED` — never
  best-effort parsed. The CLI and the platform API compare against the
  same constant in `@guuey/config`, so they can only disagree when one
  of them is out of date. Details: [Agents as code](/agents-as-code/).
- **The theme schema is additive-only.** Parsing is lenient, unknown
  keys pass through, and new tokens ship with defaults — a stored theme
  keeps parsing against future versions. See [Theming](/chat-theming/).
- **Client SDKs: the exported functions are the contract.** The SSE
  frame grammar and other wire details underneath them are internal and
  can change between releases. See
  [Build your own surface](/sdk/).

The `@guuey/*` packages are versioned in lockstep and are pre-1.0
(0.x): a minor-version bump can carry breaking changes until the
packages reach 1.0.

## The posture at launch

At launch, the platform's public contracts move to a stability posture:

- **Additive evolution.** The HTTP API
  (`https://api.us-east-1.guuey.com/v1`) and the CLI's machine-readable
  output grow by adding fields and endpoints; existing ones are not
  removed or renamed without a deprecation cycle.
- **Versioned schema.** `guuey.json` keeps the `"schema"` mechanism
  above; when a `"2"` ships, the `1 → 2` migration lands in
  `@guuey/config` so the CLI and the API pick it up together, and
  documents you wrote against `"1"` keep working.
- **Announced deprecations.** Anything scheduled for removal is
  announced with a migration path before it goes away.

## What is never a contract

Internals stay internal at every stage: the SSE frame grammar under the
SDKs, undocumented endpoints, the shape of server-rendered HTML, and
anything not described in these docs. If you find yourself depending on
one of them, tell us what the documented surface is missing.