Agent API change policy
Understand Beacon v1 compatibility, deprecation notices, removal dates, and security exceptions.
This policy applies to the documented Beacon Agent API at /agent/v1.
v1 compatibility
Beacon keeps documented /agent/v1 requests compatible while version 1 is supported.
During that period, Beacon keeps these contracts:
- A valid documented request remains valid.
- An existing field keeps its documented name, type, and meaning.
- A response keeps its documented required fields.
- An existing route keeps its documented authentication and permission model.
Beacon can add routes, optional request fields, response fields, and problem details in v1.
Clients must ignore response fields that they do not use.
Planned changes
Beacon gives at least 90 days' public notice before a planned removal or incompatible change.
The notice appears in the developer changelog. It identifies the replacement, migration steps, and earliest removal date.
Affected responses use these headers during the notice period:
| Header | Meaning |
|---|---|
Deprecation | The date when Beacon marked the contract as deprecated |
Sunset | The earliest date when Beacon can remove the contract |
Beacon keeps deprecated behavior available until the Sunset date unless the security exception applies.
A planned breaking change uses a new route major when Beacon cannot provide a compatibility layer.
Security exception
Beacon can change or remove unsafe behavior before 90 days when a delay creates a material security risk.
Beacon limits an emergency change to the smallest necessary scope.
Beacon publishes a notice and migration steps as soon as disclosure is safe.
Advance headers can be absent when they would increase the security risk.