> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Deprecations Overview
> How Suki evolves APIs and SDKs, what counts as a breaking change, and how partners learn about deprecations and migrations
Suki evolves the platform through additive changes and documented deprecations. We do not use a fixed calendar for when deprecated features are removed. Timelines depend on the change, your integration, and coordination with your partnership team.
This guide explains:
* What counts as breaking vs non-breaking
* How Suki handles deprecations
* Where to find deprecation and removal notices
* How to plan migrations
For the full schedule of known deprecations and removals, refer to the [Deprecation list](/updates/deprecations).
## What's a breaking change
Require updates to your integration:
* Removing or renaming endpoints, fields, or parameters
* Changing data types or formats
* Making optional fields required
* Tightening validation rules
* Changing default behavior in a way that affects existing clients
Work with existing code:
* New endpoints or optional fields
* New optional parameters
* Performance improvements
* Documentation clarifications
Refer to [Breaking and non-breaking changes](/updates/release-and-versioning#breaking-and-non-breaking-changes) in the release and versioning policy for more information.
## The deprecation timeline
Unlike a fixed quarterly removal schedule, Suki sets deprecation timelines per change. Your **partnership team** is the primary channel for migration dates, rollout guidance, and org-specific impact.
When we need to make a breaking change, we follow this process:
We mark the feature as deprecated in documentation, changelogs, and (for APIs) in the reference with a DEPRECATED tag. Your integration continues to work during the migration period.
Old and new approaches typically run side by side. We publish migration guides, release notes, and changelog entries with replacement APIs or SDK patterns.
We remove the deprecated feature after partners have had time to migrate. Removal timing is communicated through your partnership team and published in [Release notes](/updates/release-notes), product changelogs, and the [Deprecation list](/updates/deprecations).
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#6F5410','primaryTextColor':'#FFFFFF','primaryBorderColor':'#6F5410','lineColor':'#6F5410','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','arrowheadColor':'#6F5410','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','edgeLabelBackground':'#FFFADE'}}}%%
flowchart LR
A[Deprecation announced
in docs and changelog]
B[Migration period
old and new both work]
C[Removal published
in release notes]
A --> B --> C
classDef suki fill:#FFFADE,stroke:#6F5410,stroke-width:2px,color:#111827
class A,B,C suki
linkStyle 0 stroke:#6F5410,stroke-width:2px
linkStyle 1 stroke:#6F5410,stroke-width:2px
```
If you do not hear from your partnership team about a deprecation, review the [Deprecation list](/updates/deprecations), product changelogs, [monthly release notes](/updates/release-notes), and [announcements](/updates/announcements). Subscribe to release notes by **RSS** or **email** from the [Release notes hub](/updates/release-notes).
## How you'll know about changes
| Channel | What you get |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Partnership team** | Migration timelines, rollout guidance, and org-specific impact |
| **[Deprecation list](/updates/deprecations)** | Searchable catalog of active deprecations and past removals |
| **API reference** | DEPRECATED tags on endpoints and inline warnings on parameters |
| **Product changelogs** | Version labels, tags, and migration pointers per product line |
| **[Monthly release notes](/updates/release-notes)** | Cross-product summaries with **Deprecated** and **Removed** sections |
| **[Announcements](/updates/announcements)** | Site-wide operational notices |
API endpoints use status tags described in [API reference guidelines](/api-reference/api-guidelines). SDK breaking changes appear in migration guides such as [Migrating to Web SDK v2](/web-sdk/product-updates/migration-to-v2) and [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3).
## Planning your migration
When something you use is deprecated or removed:
1. **Assess impact**: Find every call site, config flag, or SDK option that uses the deprecated item.
2. **Confirm timing**: Ask your partnership team when removal applies to your organization if it is not listed on the [Deprecation list](/updates/deprecations).
3. **Implement replacements**: Use the linked migration guide, changelog entry, or API reference page for the recommended alternative.
4. **Test before production**: Run regression tests in staging before you deploy the update.
Product changelogs are the **authoritative source** for version boundaries. Monthly release notes give cross-product visibility but do not replace changelog detail. See [Release notes and changelogs](/updates/release-and-versioning#release-notes-and-changelogs).
## After removal
When a deprecated item is removed, behavior depends on the type of change:
| Item type | Typical response |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Endpoints** | HTTP error with a message pointing to the replacement endpoint |
| **Request fields or parameters** | Validation error if the field is sent; omit deprecated fields in new requests |
| **Response fields** | Field omitted from the response |
| **SDK properties or events** | Type or runtime errors if you still reference removed symbols; upgrade to the documented replacement |
For API error handling patterns, refer to the [API error messages](/api-reference/error-messages) page.