API Stability
General Augment has two explicit public boundaries:
| Boundary | Contract |
|---|---|
| App runtime | POST /v1/responses with a Project runtime key. This path remains stable while management moves to v3. |
| Governed management | Typed /api/v3/* APIs used by genaug and the dashboard. Project configuration commits immutable Candidate releases from one desired-state head. |
There is no public v1/v2 management compatibility layer. The v3 cutover happens before external Project onboarding, after existing test Projects are removed. Undocumented legacy routes, admin headers, local evidence files, and mutable Agent writers are not stable contracts.
Stable Runtime Contract
Section titled “Stable Runtime Contract”The Responses contract includes Project runtime-key bearer authentication, Agent and stable app-user selection, completed and failed objects, semantic SSE events, usage and correlation metadata, idempotency headers, structured-output validation, and stable machine-readable errors.
Official TypeScript and Python SDKs wrap this runtime contract only. They do not mutate Projects, identities, memory, tools, credentials, or releases.
Management Contract
Section titled “Management Contract”Management clients use generated v3 types and must tolerate additive fields. Breaking changes require a new versioned contract. A stale Project mutation fails with a semantic 409 conflict; it never overwrites a newer desired-state revision.
Secrets are accepted only through environment variables, stdin, browser OAuth, or one-time runtime-key delivery. Management and runtime credentials are not interchangeable.
Deprecation Policy
Section titled “Deprecation Policy”After external onboarding begins, stable public behavior is forward-remediated. Planned breaking changes receive migration guidance and a new versioned path or SDK major version where practical. Security, abuse-prevention, legal, provider, and Project-isolation fixes may ship faster.
Preview provider adapters, Project-authored capability schemas, and undocumented internal diagnostics may evolve without the stable-contract guarantee.
Client Guidance
Section titled “Client Guidance”- Keep runtime keys on the app backend.
- Set a stable authenticated
useron every turn. - Supply deterministic idempotency keys for retryable business actions.
- Store response, run, trace, and request IDs for support.
- Ignore unknown additive JSON fields.
- Use
genaug release diff, hosted Agent tests, and the Releases dashboard before promotion.