# Naasher API lifecycle

Versioning, compatibility, deprecation, and sunset policy for the public Naasher API.

[العربية](/api-lifecycle)

The public **Naasher API** uses a major version in its path. Current public SDK operations begin at `https://api.naasher.com/api/sdk/v1`. The major version remains stable while changes are compatible with existing clients.

## [Compatible changes within v1](#compatible-changes-within-v1)

Naasher may add endpoints, optional fields, documented enum values, or expanded limits. Clients should ignore unknown response fields and must not depend on JSON property order. An existing field is not removed, given a different meaning or type, or changed from optional to required within the same major version.

A breaking contract moves to a new major path such as `/api/sdk/v2`, with both versions available during the stated transition window.

## [Deprecation process](#deprecation-process)

When an operation or version is being retired:

1. OpenAPI marks the operation with `deprecated: true` and identifies the replacement.
2. The response includes `Deprecation` and a `Link` to this policy or the relevant migration guide.
3. After a shutdown date is approved, the response also includes an HTTP-date `Sunset` header.
4. The path remains available for at least **180 days** from the first announcement before removal.

At the last-modified date of this page, no public v1 operation was marked deprecated. Verify the live OpenAPI contract and response headers before planning an integration change.

## [Security and upstream-provider exceptions](#security-and-upstream-provider-exceptions)

Naasher may stop behavior immediately when continuing it would put customer or platform data at risk, or when a social provider removes the upstream API without a transition window. In that case, the team publishes the reason, affected surface, and recovery action in the [Naasher changelog](https://naasher.com/changelog) as soon as incident response safely allows.

This exception does not turn a provider outage into a silent success. Callers should preserve the returned error, stop unsafe retries, and reconcile remote state before replacement writes.

## [What clients should monitor](#what-clients-should-monitor)

- [OpenAPI 3.1](https://api.naasher.com/openapi.json), including each operation's `deprecated` field.
- `Deprecation`, `Sunset`, and `Link` response headers.
- The [Naasher changelog](https://naasher.com/changelog) before production upgrades.
- Stable error codes rather than message wording.
- Provider availability for the exact connected account.

Return to the [REST API reference](/en/api) for authentication, scopes, and endpoint behavior.

[REST APIAPI keys, OAuth, least-privilege scopes, endpoints, errors, and lifecycle rules for Naasher API v1.](/en/api)[MCP serverConnect a scoped AI client to Naasher through Streamable HTTP while keeping human approval before external actions.](/en/mcp)

---

Canonical URL: https://docs.naasher.com/en/api-lifecycle