Gessa API lifecycle and deprecation policy
This policy defines which Gessa machine interfaces are stable, how compatible changes ship, and the signals an agent or integration can rely on before an API version is retired.
Current supported contract
The public contract at api.gessa.ai/openapi.jsonis the compatibility authority for Gessa’s generation API. Its current stable major version is 1. Callers may omit x-api-version to use the current default or sendx-api-version: 1 to pin that major. Undocumented implementation routes are not part of this promise.
Compatible and breaking changes
Additive changes may ship within a stable major version. Examples include a new optional request field, a new response field, a new error code inside the documented error envelope, or a new operation. Integrations should ignore unknown response fields and handle unknown error codes through their documented category. Removing or renaming a field, narrowing an accepted value, changing a field’s meaning, or making an optional input required is a breaking change and requires a new major version or an explicit migration corridor.
Deprecation signals
An active operation is not marked deprecated in advance. When Gessa deprecates a public operation or version, its OpenAPI entry will set deprecated: true, affected HTTP responses will carry the standardizedDeprecation header, and a Link relation will point to migration guidance. Clients should treat that signal as a request to migrate, not as an immediate outage.
Sunset and notice
Once a retirement date is scheduled, affected responses will include the standardized Sunset header. Where a replacement exists, Gessa will also identify the successor version in migration documentation or aLink relation. Gessa targets at least 90 days of notice before retiring a generally available API version. A longer migration window may be announced for a broad or high-impact change. Security incidents and legal requirements can require faster action; any exception will be documented with the reason and safest available migration path.
Agent behavior during migration
Agents should read the OpenAPI contract at startup or build time, preserve the machine-readable error code and request identifier, and stop sending deprecated mutations before the sunset date. Do not infer replacement fields or retry a write against a new major version without validating its schema. For a contract ambiguity or missing migration link, use the developer support route before making a potentially destructive assumption.
Policy scope and updates
This policy applies to operations in the supported public OpenAPI document. MCP capabilities remain discoverable through the authenticated protocol and use their advertised OAuth scopes; draft discovery documents may evolve with their underlying specifications. Material changes to this lifecycle policy will be dated on this page and linked from the Gessa developer platform. Policy published August 26, 2026.