Deprecation

Endpoints nearing end-of-support are marked as deprecated. Clients must watch for the Deprecation and Sunset response headers and migrate to the recommended replacement before the sunset date.

Flip occasionally removes endpoints — for example when they overlap with newer alternatives or block necessary changes to the underlying service. Deprecated endpoints are shut down three months after deprecation unless explicitly communicated otherwise.

The exact sunset date is carried on every response from a deprecated endpoint in the Sunset header (see below). That header, not this document, is the authoritative source.

Do not use deprecated endpoints in new integrations. Use the deprecation window to switch to the recommended alternative.

Deprecation Headers

Every response from a deprecated endpoint carries machine-readable headers describing when the endpoint was deprecated, when it will be removed, and where to find a replacement. These headers follow RFC 9745 (Deprecation) and RFC 8594 (Sunset).

Clients — including automated agents maintaining API integrations — must treat the presence of a Deprecation header as a signal to plan migration before the Sunset date.

Headers Returned on Deprecated Endpoints

Header	RFC	Meaning	Example
`Deprecation`	RFC 9745	HTTP-date the endpoint was deprecated.	`Wed, 01 Apr 2026 00:00:00 GMT`
`Sunset`	RFC 8594	HTTP-date the endpoint will be removed. After this date, the endpoint may return `410 Gone`.	`Thu, 01 Jul 2026 00:00:00 GMT`
`Link` (`rel="deprecation"`)	RFC 9745	URL to this documentation page.	`<https://www.getflip.dev/api-docs/docs/deprecation>; rel="deprecation"`
`Link` (`rel="successor-version"`)	RFC 9745	Path of the recommended replacement endpoint. Present only when a replacement exists.	`</api/admin/channels/v4/channels/{channel_id}/archive>; rel="successor-version"`

Non-deprecated endpoints return none of these headers.

Example Response

Recommended Client Behaviour

Golden Rule: If a response contains a Deprecation header, the calling code path is on a sunset clock. Surface this to a human (or to the agent maintaining the integration) before the Sunset date passes.

Clients calling Flip APIs should implement the following:

Detect: On every response, check for the Deprecation header. Its presence is the trigger; use the Sunset date to gauge urgency.
Log a warning: Emit a structured log entry containing the request method, path, Deprecation date, Sunset date, and the successor-version link (if present). Deduplicate per endpoint per process — do not log on every call in a tight loop.
Emit a metric: Increment a counter (e.g. deprecated_endpoint_calls_total{method, path}) on every deprecated response. Counters are cheap and are what you should alert and dashboard on. The log is for humans; the metric is the source of truth for "is this endpoint still in use?".
Alert: Forward the warning to a channel a human will notice — an error tracker, a dashboard, a ticket. A silent log line in production is not enough; someone must act before the Sunset date.
Plan migration: Treat the successor-version link as the recommended replacement. If no successor link is present, check the OpenAPI spec for the endpoint's x-flip-replacement field.
Migrate before Sunset: After the sunset date, the endpoint may begin returning 410 Gone without further notice.

Guidance for Coding Agents

Agents that generate, review, or maintain API client code must:

Treat a Deprecation header observed in test runs, recorded fixtures, or CI logs as a TODO to migrate the call site.
When updating an integration, search the codebase for call sites matching the deprecated path and propose changes to the successor-version path.
Prefer opening a tracked task (issue, ticket) over a silent code change, so the migration is visible to maintainers.
Do not suppress, filter, or strip these headers from client-side logging — they are the only runtime signal that an endpoint is going away.

How Deprecation Is Marked in the Spec

Deprecated operations carry the standard deprecated: true flag alongside x-flip-status: deprecated and the date extensions that drive the runtime headers: x-flip-deprecation-date, x-flip-sunset-date, and (where applicable) x-flip-replacement.