Stability

Seven StitchAPI surfaces are experimental: they ship in the same version as everything else, but a minor release may change their shape or behaviour. Read this page before you build on one.

Experimental surfacesCopy Anchor Link

What experimental meansCopy Anchor Link

A minor release can change it, with a migration line instead of a deprecation cycle. A stable surface renames behind a @deprecated alias and drops the old name in the next major. An experimental surface changes in place, in a minor release, and the changelog lists each change with a one-line migration.

A patch release does not, with one exception. A patch release does not change an experimental surface's shape or behaviour, and that includes a bug fix that alters what a documented call returns: such a fix ships in a minor. The exception is a security fix: a patch may change behaviour (never shape) to close a vulnerability, makes the minimal change that does, and lists it under the release's ### Security heading in the changelog with a one-line migration. So if you build on one, pin the package that ships it to a patch range such as ~1.0.0 and you stay on exactly what you built against, apart from security fixes, until you choose to move. For stitchapi/llm, stitchapi/postmessage and stitchapi/pipe that package is stitchapi.

Same version, narrower promise. An experimental surface ships at the same version as the rest — no 0.x line, no prerelease tag — so installing it looks like installing anything else. The promise is what differs.

The rest of the contract still applies. Naming, typing, and config shape follow the same rules as the stable surface. The tier changes how a change ships, not what a surface may look like.

A package's command line is part of it. @stitchapi/openapi ships a CLI, stitch-openapi. Its flags, exit codes and output are covered by the same rules as the package's exports.

Marked in three places, and wherever a page teaches it. Every symbol an experimental surface exports carries an @experimental JSDoc tag, on every overload signature, so your editor shows it on hover. The surface's docs page — or its README, where no page exists yet — opens with an Experimental banner, and any other docs page whose code uses the surface carries a short note of its own. And the surface is on the list below. A stable entry point never re-exports or names an experimental symbol, so staying on stable surfaces never ties your code to an experimental shape.

The surfacesCopy Anchor Link

Since is the version in which the surface entered the tier.

toOpenApi in stitchapi/registry, which exports a stitch as an OpenAPI document, is not on the list: it keeps the full 1.x promise. @stitchapi/openapi, the generator that ejects stitch source from a document, is on it — ejected code is yours, so changing what the generator writes breaks nobody who already ran it.

Graduating and demotingCopy Anchor Link

A surface graduates when its tag comes off, in a minor release. All three conditions have to hold:

1. A dedicated docs-site page exists for it. A README, or a note on another page, does not count.
2. No open issue proposes a change to its public shape.
3. One minor release has shipped since its Since version with no breaking changelog entry for it: nothing marked BREAKING CHANGE that names the surface or one of its exports.

The changelog records the graduation, and from that release the surface carries the full 1.x promise. The reverse direction is a major: moving a stable surface into this tier withdraws a promise already made, so it never happens in a minor.

The rule is P26 of the API contract; a lint reads its member list and fails the build if an exported symbol of a listed surface is missing its tag, or if a stable file imports one.

See alsoCopy Anchor Link