#API Deprecation Policy

2 min read

#Current Status

No endpoints listed in this API reference are currently deprecated. Current API responses do not emit Deprecation or Sunset headers.

This status is scoped to public, partner, and selected first-party portal API surfaces that are explicitly listed in this reference. Internal implementation deprecations, when present, do not change the API contract unless an endpoint in this reference is explicitly marked as deprecated.

Field-level compatibility deprecations are documented with the affected response shape, but they do not make the whole endpoint deprecated. For example, the billing overview response currently keeps the legacy billing.metered_usage field temporarily while clients migrate to billing.metered_usage_lines; that field-level compatibility note does not emit Deprecation or Sunset headers.

#Deprecation Process

When an endpoint is scheduled for removal, AiDial communicates the change through:

  1. Deprecation response header: Affected endpoint responses include a Deprecation header. The header value and effective date will be documented with the endpoint when introduced.
  2. Dated reference notice: The affected endpoint documentation includes the deprecation date, planned removal timeline, and migration guidance where applicable.
  3. Reference badge: The endpoint documentation in the API reference is marked with a Deprecated badge.

Specific timelines and migration guidance will be published before any public, partner, or selected first-party portal endpoint in this reference is deprecated.

When a response field is deprecated without deprecating the endpoint, the affected response table documents the field, the replacement where applicable, and the compatibility purpose.

#Feature-Flagged and Non-GA Endpoints

Feature-flagged, operational, and non-GA endpoints are not part of the partner API unless they are promoted to generally available status and added to this reference.

Portal-only routes are partner integration contracts only when an endpoint page explicitly documents that integration surface. Selected first-party portal API surfaces may appear in this reference for portal contract clarity, but that does not make every mounted portal-only route a partner endpoint.

Maintainers track endpoint classification in the internal endpoint visibility manifest. That manifest is documentation governance; it is not a runtime feature flag or access-control mechanism.