API Stability Policy

Versioning Scheme

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

The current path version is v1. The runtime artifact itself is pre-1.0 (0.1.0), so the /v1/ surface is not yet frozen. The guarantees below describe the contract we are converging on for a 1.0 release, not a commitment that holds today.

Stability Guarantee

OGuardAI is pre-1.0 (0.1.0). The /v1/ surface may still change while we stabilize toward 1.0. At 1.0 we intend the following to hold for endpoints under /v1/:

• 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.

Until 1.0, treat these as the direction of travel rather than firm guarantees.

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

These windows are the policy we intend to adopt at 1.0. Before 1.0 they are not yet binding.

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.

Removing a key from the session keyring invalidates every blob sealed under it, regardless of version; a multi-key rotation that retains the old key keeps existing blobs valid until their TTL. This is a security mechanism, not a compatibility issue.

SDK Versioning

SDK versions (TypeScript, Python, Go, Java) 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.

Version Reporting

The running server version is reported in the GET /v1/health response body as the version field (currently 0.1.0). Each transform and rehydrate response carries a trace_id (UUID) in its body for request correlation.

A dedicated X-OGuardAI-Version response header and an X-Request-Id header are planned but not yet emitted. Until they ship, read the version from /v1/health and correlate requests via the response trace_id.