---
title: "Versioning and deprecation"
description: "Understand API v1 compatibility boundaries, current notification limitations and a practical upgrade checklist."
slug: "/docs/v1/api/versioning-and-deprecation"
section: "API reference"
order: 45
audience: "all"
level: "intermediate"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/start/authentication", "/docs/v1/api/conventions"]
draft: false
---
Use the versioned API contract and test upgrades; no numeric deprecation-notice guarantee is currently established.

## What you will learn
- Identify breaking versus additive contract changes.
- Separate actual policy from future commitments.
- Use a complete upgrade-guide template.

## Prerequisites
- Read [API conventions](/docs/v1/api/conventions).
- Complete [the Sandbox quickstart](/docs/v1/start/quickstart).

## Current v1 boundary
The URI prefix /api/v1 identifies the current licensing contract. There is no registered /api/v2 contract. SDK 1.0.0 is a package version, not a second API version. There is no date-based API-version negotiation header. Unknown/wrong-version routes return the documented router error.
The intended compatibility practice is to preserve documented v1 request/response meaning within v1. This is a documentation/maintenance policy, not evidence of a contractual support term or SLA. The current code and signed-byte vectors are the auditable behavior. Known bugs are documented, not recast as desirable guarantees.

## Breaking and additive changes
| Change | Compatibility consideration |
| --- | --- |
| Remove/rename an operation or required field | Breaking |
| Add a required request header/credential/[scope](/docs/v1/start/glossary#scope) | Breaking |
| Change a field type/nullability/enum meaning or status semantics | Potentially breaking; test strict clients and access policy |
| Change canonical bytes, signature algorithm or trusted-key distribution | Security-critical breaking/migration concern |
| Add an optional field or new operation | Usually additive, but strict schema consumers must deliberately handle unknown fields |
| Add an error code | Clients must fail closed on unknown codes and show a safe fallback |
| Correct documentation to match unchanged source | Documentation correction, not necessarily a new API release |
Response schemas deliberately show every current field. If you generate clients with strict unknown-field rejection, review additive changes instead of assuming they are invisible. Do not accept an unsigned or invalid response merely to tolerate a changed schema.

## Notice periods and announcements
No minimum numeric notice period, deprecation email pipeline, Sunset/Deprecation header or published v1 end-of-support date is implemented/confirmed. Do not invent30/90/180-day promises. API responses do not currently include those deprecation headers. Refer to the actual changelog and contact hi@kdpika.com for an announced migration; absence of a header is not an unlimited-lifetime guarantee.
Before a breaking release is offered, its owner should approve the supported versions, advance notice dates, migration guide, [delivery](/docs/v1/start/glossary#delivery) channels and retirement policy. The approved notice belongs in the changelog and account communication. This is a maintenance recommendation, not a claim that notifications have already been sent.

## Upgrade-guide template
| Section | Required concrete content |
| --- | --- |
| Target/source versions | Exact API/SDK revisions and supported runtimes |
| Affected integrations | Named operations, fields, headers, errors, signatures and storage paths |
| Before and after | Full runnable requests/responses, not code fragments |
| Data and credentials | Whether keys/tokens/cache formats change, safe handling and rollback |
| Test procedure | Sandbox positive/negative/vector/expiry/offline cases with expected outcomes |
| Rollout | Pinning, staged deployment, monitoring and support escalation |
| Retirement | Owner-approved notice, actual dates/channels and supported overlap |
| Verification | Source evidence, executed samples and remaining limitations |
1. Pin your current SDK/client version and keep a tested rollback package. Expected: the existing installation path remains recoverable.
2. Compare the exact operation schemas, error handling and signature vectors. Expected: each changed assumption is identified.
3. Run the new client through Sandbox [activation](/docs/v1/start/glossary#activation)/validation/refusal/deactivation and offline/clock tests as applicable. Expected: no [feature](/docs/v1/start/glossary#feature) grant after a failed verification.
4. Update secure storage and credentials only according to the actual migration. Expected: no accidental token sharing or broad key exposure.
5. Roll out gradually and watch safe request-ID/error metadata. Expected: failures are visible without payload/credential logging.
6. Retire the old client only after your verified rollout criteria and any actual notice period are satisfied. Expected: no invented overlap guarantee.

## Expected result
Upgrade decisions are based on an explicit contract diff and executed Sandbox checks, with current policy limitations visible.

## Common mistakes
- Using an SDK version as the API path or inventing a Stripe-style date header.
- Assuming a fixed deprecation notice/Sunset header exists because other APIs use one.

## Security notes
Test signed-byte compatibility and semantic refusal paths before rollout. Never recover from a version mismatch by bypassing signature, TLS or installation checks.

## Troubleshooting
| Symptom | Cause | Action |
| --- | --- | --- |
| Unknown route after upgrade | Unsupported API prefix/path | Use documented v1 until an actual new version is offered |
| No Sunset header | Not implemented in current API | Read the actual announced migration and ask support |
| Signature mismatch | Changed client serialization/trust or known canonicalization limitation | Fail closed and run the exact published vectors |

## Next steps
Review [the endpoint reference](/docs/v1/api/public-key) and [signature verification](/docs/v1/security/verify-ed25519).

## Related
- [Authentication](/docs/v1/start/authentication)
- [API conventions](/docs/v1/api/conventions)
- [License lifecycle](/docs/v1/start/license-lifecycle)