# API Stability

Source: https://docs.generalaugment.com/guides/api-stability/
Description: Public v1 compatibility and deprecation policy for General Augment app integrations.

General Augment publishes a platform-wide stability policy for public app-developer
surfaces. It applies to all integrators and is not a project-specific code freeze.

## Stable v1 Surfaces

These documented surfaces are stable public v1 contracts today:

| Surface | Stable contract |
| --- | --- |
| Responses API | `POST /v1/responses`, project-scoped bearer auth, documented request fields, completed/failed response shape, usage object, metadata correlation fields, idempotency headers, structured-output failure contract, and semantic SSE event names. |
| Project API keys and auth | Project-scoped API keys, key create/list/update/revoke lifecycle, one-time raw-key display, masked listing, bearer auth for app calls, and documented `X-Admin-Key` compatibility. |
| Public memory API | Memory store, search, profile, single-delete, and user-purge routes under `/api/v1/agent/memory/*`. |
| App-facing observability and operations | Usage, logs, trace lookup, tool-call audit, and approval endpoints documented for app operators, including stable public error `code` and `reason` fields. |
| Tool registry and project tool policy | Built-in tool listing metadata, stability labels, project tool allowlist behavior, generated-tool risk defaults, and approval API behavior. |
| Health and app polling | `GET /health/ready` for hosted app readiness polling, `GET /v1/health` as the compatibility readiness path once status smoke verifies it, `GET /health/live` for process liveness, and `GET /health/detailed` for operator smoke tests. |
| SDK helper names | Public TypeScript and Python SDK helpers documented in the SDK reference, while keeping existing compatibility aliases where documented. |

The generated OpenAPI reference can include operator or internal-adjacent routes. A route
is part of the stable app-developer contract only when it is documented in public docs or
explicitly marked stable in release notes.

## Compatibility Commitment

For stable public v1 surfaces, General Augment aims to preserve backwards compatibility:

- Existing documented routes, auth methods, required request fields, response object
structure, and machine-switchable error `code` and `reason` values should continue to
work.
- Additive changes, such as new optional request fields, new response metadata fields,
new enum values, new SDK helpers, or new endpoints, may ship without advance notice.
- Planned breaking changes to stable public v1 surfaces receive at least 90 days notice
before removal or required migration.
- Major breaks should use a new versioned path, field, header, or SDK major version
where practical, instead of changing current v1 behavior in place.

Clients should ignore unknown response fields and handle unknown enum values
defensively.

## Deprecation Notice

When General Augment plans a breaking change to a stable public v1 surface, the notice
should include what is changing, which routes or fields are affected, migration steps,
the earliest removal date, and where to report integration blockers.

Notices should appear in public docs or the changelog. When a change materially affects
active production projects, General Augment should also use available customer channels
such as dashboard messaging, email, or partner support threads.

## Exceptions

General Augment may change behavior with less or no notice when required for:

- urgent security, abuse-prevention, privacy, or tenant-isolation fixes;
- legal, compliance, provider, or infrastructure requirements outside General Augment's
control;
- changes to undocumented behavior, invalid inputs, or bug-compatible behavior that
conflicts with the documented contract;
- preview, experimental, or explicitly project-defined surfaces.

Experimental or project-defined surfaces include generated OpenAPI/MCP tools, app-owned
tool schemas, preview tools marked `experimental`, local mock-server fixtures, and
undocumented operator endpoints.

## Client Guidance

Build integrations so they tolerate additive platform changes:

- keep project-scoped API keys on your backend;
- store response IDs, trace IDs, and request IDs for support;
- ignore unknown JSON fields;
- handle unknown tool stability values, approval statuses, and error reasons with a
safe fallback;
- use idempotency keys for retryable `/v1/responses` and memory writes;
- use `GET /health/ready` for hosted app polling rather than waiting on the public status page; rely on `GET /v1/health` only after the status smoke verifies the compatibility path.