Compatibility

Document revision 2.0.0 is an intentional breaking reset of the earlier staging /v1 contract: run and approval paths, resource identities and response types changed together. Existing integrations must update their requests and generated types. This reset is an explicit exception to the previous six-month notice promise; no prior notice or external client migration is claimed. The complete change record is docs/api-reset-2.md in the repository. The policy below applies to subsequent changes.

Response objects are open: new fields can ship within /v1, and clients should ignore fields they do not recognize. Send only documented request keys; request bodies are strict.

Enums are closed. Adding an enum value is a breaking change because generated clients validate against the published union. New values must use a new field or operation rather than extending a published enum in place. Treat an unknown enum value as a client/schema mismatch. Event discriminators are also defined by the published schema; do not assume they can expand silently.

Breaking changes require /v2, with Deprecation and Sunset headers on /v1 at least six months before removal. Follow the generated reference for the deployed schema.

Send X-Request-Id with 8–64 characters from [A-Za-z0-9._-] for correlation. The response echoes the id it used; include it when reporting a problem. See Errors for the format and reason catalog.