Versioning and deprecation

How we evolve the Agent API without breaking existing integrations.

Stability

The Agent API runs under the /v1/agent prefix. Within v1 we only make backwards-compatible changes: adding a new endpoint, a new optional parameter, or a new field in a response. These changes require no action on your part.

What we consider compatible

Adding endpoints, optional request parameters, new response fields, and new enum values. Your integration should ignore unknown fields and must not depend on field ordering.

Breaking changes

Changes that are not backwards-compatible (removing/renaming a field, changing a type, changing behavior) are released under a new prefix version (e.g. a future /v2/agent). We keep the previous version running for an announced deprecation period.

Deprecation policy

We announce deprecations in advance in the changelog with an end-of-support date. We keep the old version/endpoint working for at least 90 days before shutting it down. Where possible, deprecated endpoints return a Deprecation and Sunset header with the date.

Recommendations

Watch the changelog, pin to /v1/agent, parse responses tolerantly, and use the sandbox to verify before rolling out changes.