OmegaEngine · API Contract

API versioning & deprecation policy

Pin a date-based API version per request with the API-Version header. Versions are announced, deprecated, and sunset on a published schedule — never silently.

Requesting a version

Send the version you built against in the API-Version request header. Omega-Version and X-API-Version are accepted as aliases, in that priority order.

curl

curl https://omegaengine.ai/api/authorize \
  -H "x-api-key: $OMEGA_API_KEY" \
  -H "API-Version: 2026-03-13" \
  -d '{ "action": { "type": "http.request", "url": "https://api.example.com" } }'

No header — you get the current version (2026-03-13). Pinning is recommended for production integrations.
Known version— the request is served under that version's contract, and the response echoes it in X-API-Version.
Unknown or malformed version — the request is rejected with 400 UNSUPPORTED_API_VERSION and the list of supported versions. We never silently serve a different contract than the one you pinned.

400 — unknown version

{
  "ok": false,
  "error": "UNSUPPORTED_API_VERSION",
  "message": "Unknown API version '2020-01-01'. Send a supported version in the API-Version header, or omit it to use the current version (2026-03-13).",
  "supportedVersions": ["2026-03-13","2026-03-08","2026-03-07","2026-01-26"],
  "docs": "/docs/api/versioning"
}

Supported versions

This table is rendered from the same version registry the API enforces. The live catalog is also served at GET /api/versions (no auth).

Version	Status	Deprecation date	Sunset date	Changelog
`2026-03-13`	Current	—	—	RBAC scoping, structured error taxonomy, decision cache, circuit breaker
`2026-03-08`	Supported	2026-09-08	2027-03-08	Proxy decomposition, cognitive memory, compliance frameworks
`2026-03-07`	Supported	2026-09-07	2027-03-07	Idempotency, replay, graceful shutdown
`2026-01-26`	Deprecated	2026-07-26	2027-01-26	Initial release — v1 decision engine

Response headers

Every /api/* response tells you which version served it, and — following RFC 8594 — when that version is scheduled to be retired.

Header	Meaning
`X-API-Version`	The version that served this request (also sent as X-Omega-API-Version).
`Deprecation`	RFC 8594 — the date this version was (or will be) deprecated. Present once a deprecation date is published.
`Sunset`	RFC 8594 — the date this version stops being served. Present once a sunset date is published.
`X-Omega-Version-Warning`	Human-readable migration warning, sent only when the version you pinned is deprecated or sunset.
`Link`	rel="successor-version" pointer to the migration guide, sent alongside the warning.

Deprecation policy

6 months notice, minimum. When we deprecate an API version or endpoint, we publish a deprecation date at least 6 months before the sunset date. Until sunset, the deprecated surface keeps working under its documented contract.
Machine-readable warnings. Deprecations are announced in the response headers above and in this document — you can alert on the Deprecation header in your own monitoring.
No breaking changes within a version. Backwards-compatible additions (new optional fields, new endpoints) ship without a version bump. Anything breaking gets a new dated version.

Deprecations index

Every currently deprecated surface, in one place. When something here gains a sunset date, that date appears at least 6 months out.

Surface	Status	Replacement	Sunset
`/api/redteam/subscription`	Legacy — retained for existing scheduled-scan workflows and sales-led red-team entitlements. Not offered to new customers.	Agent Action Control Plane tiers plus Red Team Assessment / Evidence Pack services.	No sunset date scheduled. If one is set, existing customers get at least 6 months notice here and in the Sunset header.
API version `2026-01-26`	Deprecated (deprecation date 2026-07-26).	`2026-03-13`	2027-01-26