Second Shift Agents API versioning and deprecation policy

The stable Client API uses a major version in the URL, currently /api/v1. A breaking contract change requires a new major path. Compatible additions—such as a new optional field, response property, endpoint, or error code—may be added within the current major version. Integrations should ignore unknown response properties and branch on documented machine-readable error codes.

Deprecation signals

When Second Shift deprecates a public operation, the OpenAPI description and developer documentation will identify the replacement. Responses from the deprecated operation will include a Deprecation header and a Link header with rel="deprecation". Once a removal date is scheduled, responses will also include a Sunset header using an HTTP-date. Second Shift intends to provide at least 90 days between a scheduled public deprecation notice and removal when security, legal, or urgent reliability constraints do not require faster action.

No public Client API operation is currently deprecated. A missing Deprecation or Sunset header therefore means the operation is active; it is not an undocumented removal date.

Operational compatibility

Authentication, authorization, organization isolation, workflow grants, approval gates, idempotency, audit requirements, and rate limits are part of the operating contract. A new version does not silently expand an agent's authority. Current schemas and operation descriptions are published in OpenAPI 3.1, and integration guidance is at /docs.