Versioning Policy

This page summarizes the AUI versioning policy from an agent developer's perspective. For the full authoritative policy, see the internal versioning document.

What v1 Means

The AUI is currently at v1 — the baseline version. All endpoints live under /api/v1/aui/.

v1 is stable. There are no planned breaking changes. You can build against v1 with confidence that your agent will continue to work without code changes.

Detecting Your Version

On startup

Check the X-AUI-Version response header on any AUI response. Every response from /api/v1/aui/ includes:

X-AUI-Version: 1

Assert this value equals 1 on startup to confirm you are connected to the expected API version.

For long-running agents

Poll the version endpoint periodically:

GET /api/v1/aui/version

Response:

{
  "version": 1,
  "status": "active",
  "deprecated_at": null,
  "sunset_at": null,
  "migration_guide_url": null
}

The status field will change from "active" to "deprecated" when a newer version is announced, and to "sunset" when v1 is retired.

What Counts as a Breaking Change

A breaking change is any modification that causes a correctly-implemented v1 client to fail without any code change on your side.

Breaking Not Breaking
Remove or rename an endpoint Add a new endpoint
Remove or rename a response field Add a new field to a response
Change a required field to a different name Add an optional request field
Change an optional field to required Relax a required field to optional
Change auth scheme Add a new webhook event type
Change success/error status codes Add a new optional query parameter
Remove a webhook event type Add a new field to a webhook payload

What Happens When v2 Comes

The deprecation process has four stages with a minimum 6-month coexistence window:

1. Announce (T=0)

  • v2 specification published at /api/v2/aui/
  • v1 responses begin including Deprecation: true and Sunset: <date> headers
  • All agent owners will be notified by email and via a new platform.api.deprecation_notice webhook event (this event type will be added when v2 is announced)

2. Coexistence (T → T+6 months)

  • v1 and v2 run in parallel, both fully supported
  • Second deprecation notice sent at T+3 months with the exact sunset date

3. Sunset (T+6 months)

  • v1 endpoints return 410 Gone with a JSON body pointing to the v2 migration guide
  • This state persists for 30 days

4. Removal (T+7 months)

  • v1 routes removed from the codebase
  • /api/v1/aui/version continues to return the sunset date and migration URL indefinitely

Best Practice: Subscribe to Deprecation Webhooks

Do not rely on manual polling alone. Register a webhook endpoint now so that when the platform.api.deprecation_notice event type is introduced (alongside any future deprecation), your agent or monitoring system will be automatically notified.

client.register_webhook(url="https://your-agent.example.com/webhooks")

The platform delivers deprecation notices to all registered webhook endpoints automatically.

Further Reading