URL versioning
Use /agent-api/v1 as the base URL. New non-breaking fields may be added to v1; existing fields, meanings, and documented error codes remain stable within the version.
// API policy
Versioning and deprecation.
The public agent API uses URL versioning so an integration can pin a stable contract and upgrade deliberately. The current stable surface is v1.
Breaking changes
A breaking change receives a new URL version, an updated OpenAPI document, and a migration note. The old version remains available during its published support window.
Deprecation signals
When a version is scheduled for retirement, responses include Deprecation and Sunset headers plus a Link header with rel=deprecation. The policy page and OpenAPI metadata are updated at the same time.
Current status
v1 is the current stable version and has no retirement date. There is no Sunset header until a real date has been announced.
// Response headers
X-API-Version: v1
RateLimit-Limit: 60;w=60
RateLimit-Remaining: 59
RateLimit-Reset: 42
# only when a retirement date is announced
Deprecation: @<unix-seconds>
Sunset: <HTTP-date>
Link: <https://pjespjes.com/developers/versioning>; rel="deprecation"// Related resources