API Stability Policy

Versioning Scheme

All public API endpoints are versioned with a path prefix: /v1/, /v2/, etc.

The current stable version is v1.

Stability Guarantee

All endpoints under /v1/ are stable. This means:

• Existing request fields will not be removed or change type.
• Existing response fields will not be removed or change type.
• Existing error codes will not change meaning.
• Existing endpoint paths will not be renamed or removed.
• Existing default values will not change.

What Is a Breaking Change

The following changes are breaking and will only occur in a new major version (/v2/):

• Removing a request or response field.
• Changing the type of a field (e.g., string to integer).
• Changing the meaning or behavior of an existing field.
• Renaming an endpoint path.
• Removing an endpoint.
• Changing a default value.
• Changing an error code's meaning.
• Changing authentication requirements for existing endpoints.

What Is NOT a Breaking Change

The following changes are non-breaking and may occur within /v1/ at any time:

• Adding new optional fields to request bodies.
• Adding new fields to response bodies.
• Adding new endpoints (e.g., /v1/revoke, /v1/batch).
• Adding new entity types to the detection engine.
• Adding new error codes.
• Adding new policy configuration keys.
• Adding new optional query parameters.
• Improving detection accuracy (fewer false negatives or false positives).
• Reducing latency.

Clients must ignore unknown fields in responses. Clients that fail on unknown fields will break when new response fields are added.

Deprecation Policy

When a feature or endpoint is scheduled for removal:

1. Announcement: Deprecation notice published in the changelog and API response headers (Deprecation: true, Sunset: <date>).
2. Minimum notice period: 6 months from announcement to removal.
3. Migration guide: Documentation provided for the replacement feature.
4. Removal: The deprecated feature is removed in the next major version only.

Deprecated features continue to function without behavioral changes during the notice period.

Version Lifecycle

When v2 is released:

• v1 will enter maintenance mode (security fixes only) for at least 12 months.
• v1 and v2 will run concurrently on the same server instance.
• Migration tooling will be provided.

Session State Compatibility

Session state blobs created by a v1 server can be consumed by any v1 server at the same or later patch version. Session blobs are not guaranteed to be compatible across major versions.

Key rotation invalidates all existing session blobs regardless of version. This is a security mechanism, not a compatibility issue.

SDK Versioning

SDK versions (TypeScript, Python) follow semantic versioning independently from the API version. SDK major version bumps may occur for SDK-specific reasons (e.g., dropping a language version) without implying an API version change.

Header Contract

Every API response includes:

X-OGuardAI-Version: 1.0.0
X-Request-Id: <uuid>

Clients may use X-OGuardAI-Version to verify server compatibility.