Breaking changes, new endpoints, and deprecations by version for the OGuardAI API

Track breaking changes, new endpoints, and deprecations across OGuardAI API versions.

Versioning Policy

The OGuardAI API follows semantic versioning. All endpoints are served under the /v1 prefix. Within a major version:

Patch releases (e.g., 0.1.1) contain bug fixes only. No API changes.
Minor releases (e.g., 0.2.0) may add new endpoints, new optional fields, or new enum values. Existing endpoints and fields remain backward-compatible.
Major releases (e.g., 1.0.0) may introduce breaking changes to existing endpoints, request/response schemas, or authentication mechanisms.

New optional fields in responses are not considered breaking changes. Clients should ignore unknown fields.

v0.1.0 -- Initial Release

Date: 2026-04-01

Status: Current

This is the first public release of the OGuardAI API. All endpoints, request/response schemas, and error codes documented below represent the initial API surface.

No breaking changes yet -- this is the first release.

Core Endpoints

Method	Path	Description
`POST`	`/v1/transform`	Transform text, replacing detected entities with semantic tokens
`POST`	`/v1/rehydrate`	Restore semantic tokens in LLM output to original values
`POST`	`/v1/detect`	Detect entities in text without transforming
`POST`	`/v1/evaluate-policy`	Evaluate policy against entities (dry run)
`GET`	`/v1/health`	Runtime health check (always public)
`GET`	`/v1/capabilities`	List entity types, languages, and detectors (always public)
`GET`	`/v1/diagnostics`	Runtime diagnostics -- detector mode, config, versions (Admin scope required)
`GET`	`/metrics`	Prometheus metrics endpoint (Admin scope required)

Streaming Endpoints

Method	Path	Description
`POST`	`/v1/transform/stream`	Streaming transform via Server-Sent Events (SSE)
`POST`	`/v1/rehydrate/stream`	Streaming rehydrate via SSE

File and Image Endpoints

Method	Path	Description
`POST`	`/v1/transform/file`	Transform an uploaded file (multipart form data)
`POST`	`/v1/transform/image`	Transform text detected in an image via OCR
`POST`	`/v1/rehydrate/file`	Rehydrate an uploaded file (multipart form data)
`POST`	`/v1/redact/image`	Redact PII regions in an image

Batch Endpoints

Method	Path	Description
`POST`	`/v1/batch/transform`	Batch transform multiple inputs in one request
`POST`	`/v1/batch/detect`	Batch detect entities in multiple inputs

RAG Endpoints

Method	Path	Description
`POST`	`/v1/rag/ingest`	Ingest a document for RAG with PII protection
`POST`	`/v1/rag/query`	Query RAG index with PII-safe context
`POST`	`/v1/rag/context`	Retrieve RAG context chunks (tokenized)
`POST`	`/v1/rag/answer`	Generate a RAG answer with automatic rehydration
`POST`	`/v1/rag/delete`	Delete ingested RAG documents

Revocation Endpoints

Method	Path	Description
`POST`	`/v1/revoke`	Revoke a single entity (makes it permanently non-restorable)
`POST`	`/v1/revoke/bulk`	Revoke multiple entities in one request
`GET`	`/v1/revocations/count`	Get the count of revoked entities

Admin Endpoints

Method	Path	Description
`POST`	`/v1/admin/policy/validate`	Validate policy configuration files (requires `admin` scope)

Authentication

Two authentication methods are supported:

API Key: Send in the X-API-Key header
JWT Bearer Token: Send in the Authorization: Bearer <token> header

Five authorization scopes are available: transform, rehydrate, detect, policy, admin. When auth is disabled (default for development), all endpoints are accessible without credentials.

Request/Response Format

All request and response bodies use JSON (Content-Type: application/json), except file upload endpoints which use multipart form data.
Transform accepts three input modes: input (plain text), input_json (structured JSON), or input_messages (OpenAI-format chat messages). Exactly one is required.
Session state is returned as an encrypted blob in transform responses and must be passed back to rehydrate requests.
Six restore modes are supported: full, partial, masked, formatted, abstract, none.

Error Codes

Code	HTTP Status	Description
`GUARDAI_INVALID_INPUT`	400	Malformed request, missing fields, type mismatch
`GUARDAI_BAD_REQUEST`	400	Generic bad request
`GUARDAI_AUTH_FAILED`	401	Missing or invalid credentials
`GUARDAI_POLICY_DENIED`	403	Policy blocks the entity type or insufficient scope
`GUARDAI_SESSION_EXPIRED`	410	Session TTL elapsed or sealed blob integrity check failed
`GUARDAI_PAYLOAD_TOO_LARGE`	413	Request exceeds configured size limit
`GUARDAI_OUTPUT_BLOCKED`	422	Output guard blocked response due to hallucinated PII
`GUARDAI_TOKEN_REPAIR_FAILED`	422	Token repair could not resolve tokens in LLM output
`GUARDAI_DETECTION_FAILED`	500	Detector service down or detection failed
`GUARDAI_INTERNAL_ERROR`	500	Unexpected server error

Known Limitations in v0.1.0

RAG and revocation scopes: The rag and revoke authorization scopes are not yet implemented. RAG and revoke endpoints currently require one of the existing scopes (typically transform or admin).
Streaming error recovery: If a detection error occurs mid-stream, the SSE connection is closed. Partial results are not recoverable.
Batch size limits: Batch endpoints accept a maximum of 100 items per request. This limit is not yet configurable.

Upcoming Changes

The following changes are planned for future releases. These are not commitments -- they reflect current development direction and may change.

v0.2.0 (Planned)

New scopes: Dedicated rag and revoke authorization scopes for RAG and revocation endpoints.
Configurable batch limits: Server-side configuration for maximum batch size.
Webhook notifications: Optional webhook delivery for async batch completion events.

v1.0.0 (Planned -- Stable Release)

API stability guarantee: All v1 endpoints will follow strict backward compatibility. Breaking changes will only occur in v2.
Potential breaking changes from v0.x:
- Error code prefix may change from GUARDAI_ to a shorter form.
- The entities array in transform responses may move to a separate diagnostic endpoint to reduce default response size.
- Session state format may change (existing sealed blobs from v0.x will not be compatible with v1.0).

These potential breaking changes will be documented in detail before the v1.0.0 release, with migration guidance.

API Reference -- Complete endpoint documentation with request/response examples
API Stability -- Stability tiers and deprecation policy
Migration Guide -- Guidance for upgrading between versions

API Changelog