API lifecycle

Compatibility within a version

ViperCapture may add optional request fields, response fields, output formats, error codes, documentation, and new endpoints within /v1. Existing fields keep their documented meaning, and unknown request fields remain rejected so caller mistakes fail visibly. Integrations must ignore response fields they do not understand and should branch on the stable error code, not on human-readable message text.

Breaking changes

An incompatible request or response change requires a new URL version such as /v2. The previous stable version remains documented during its deprecation window. Security fixes may narrow unsafe behavior without a version change when preserving that behavior would put users, target sites, or the service at risk.

Deprecation signals

When an endpoint or API version is deprecated, affected responses will include a standards-track Deprecation header with the deprecation date and a Link header with rel="deprecation" pointing to migration guidance. Documentation and the OpenAPI description will identify the replacement. ViperCapture does not emit these headers on active endpoints because doing so would falsely mark them as deprecated.

Sunset policy

A deprecated surface will normally receive at least six months of notice before removal. Once a removal date is committed, affected responses will also include the HTTP Sunset header with that date. The migration page may name a longer support period. Emergency retirement can be shorter only for an actively exploited security issue, legal requirement, provider shutdown, or another condition where continued operation is unsafe or impossible.

Agent behavior

Agents should record response headers, follow the linked migration guide, move to the replacement before the sunset date, and avoid beginning new integrations against a deprecated operation. The RateLimit, RateLimit-Policy, Retry-After, and X-Request-Id headers are independent lifecycle signals and should continue to be honored throughout a migration.