API Lifecycle and Compatibility

This policy applies to the supported customer endpoints and Harness MCP tools published at https://topline.build/docs.

Stability

The generated endpoint reference labels the current customer API as stable. Stable means existing integrations should continue working across additive releases when they follow documented discovery, authorization, and response handling practices.

Internal application routes, workforce-task bridge tools, undocumented fields, and implementation details are not part of the external compatibility promise.

Backward-compatible changes

Topline may add endpoints, MCP tools, optional request fields, response fields, enum values, error detail, and OAuth scopes. Clients must ignore unknown response fields and discover the active MCP tool list with tools/list.

Breaking changes

A change is breaking when it removes or renames a stable endpoint, tool, or required response meaning; adds a required request field; narrows accepted input; or changes authentication or authorization in a way that invalidates an existing supported integration.

Breaking changes require:

1. a changelog entry and migration guide;
2. a replacement available before removal;
3. a minimum 90-day deprecation window unless an active security issue requires faster action; and
4. direct notice to known affected customers when practical.

MCP protocol versions

Clients negotiate a supported MCP protocol version during initialize and send the negotiated version in subsequent requests. A client must not assume that the newest protocol version is the only accepted version.

Deprecation signals

Deprecated behavior is identified in the changelog and relevant guide. HTTP endpoints may also use standard Deprecation, Sunset, and Link headers when a dated removal is scheduled.

Security exception

Topline may restrict or remove behavior without the normal window when needed to prevent credential exposure, tenant-boundary violations, data loss, or active abuse. The changelog will explain the customer impact without publishing exploit details.