---
title: API Versioning & Deprecation Policy
description: GAAPx REST API versioning strategy, deprecation lifecycle, and RFC 8594 Sunset header specifications.
sidebar_label: Versioning & Deprecation
---

# API Versioning & Deprecation Policy

GAAPx provides deterministic, mission-critical financial automation. To ensure continuous stability for autonomous AI agents, ERP integrations, and financial systems, we enforce a strict versioning and deprecation lifecycle.

---

## 1. Versioning Strategy

- **URL Path Versioning**: All production and sandbox API endpoints include an explicit major version identifier in the path (e.g., `https://api.gaapx.ai/v1`, `https://sandbox.gaapx.ai/v1`).
- **Backward Compatibility**: Non-breaking changes (such as adding optional request parameters or new response fields) are introduced seamlessly within the current major version (`v1`).
- **Major Version Increments**: Backward-incompatible changes trigger a new major version path (e.g. `/v2`).

---

## 2. Deprecation Lifecycle & 180-Day Guarantee

When an endpoint or version is scheduled for retirement:

1. **Advance Notice**: GAAPx guarantees a minimum **180-day deprecation notice period** before any endpoint is retired.
2. **HTTP Deprecation Headers (RFC 8594)**: Deprecated endpoints return standard HTTP headers on every request:
   - `Deprecation: @<timestamp>` — The Unix timestamp when the endpoint was deprecated.
   - `Sunset: <http-date>` — The exact GMT date and time when the endpoint will cease responding.
   - `Link: <https://docs.gaapx.ai/versioning>; rel="sunset"` — Link to deprecation documentation.
3. **Machine Readability**: AI agents and automated clients can programmatically monitor the `Deprecation` and `Sunset` headers to preemptively alert engineering teams.

---

## 3. Example Deprecation Response Headers

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Deprecation: @1790726400
Sunset: Wed, 01 Oct 2027 00:00:00 GMT
Link: <https://docs.gaapx.ai/versioning.md>; rel="sunset", <https://docs.gaapx.ai/openapi.json>; rel="service-desc"
RateLimit-Limit: 1000
RateLimit-Remaining: 999
RateLimit-Reset: 60
```

---

## 4. Current API Status

| API Surface | Current Version | Status | Deprecation Notice | Sunset Date |
| :--- | :--- | :--- | :--- | :--- |
| **REST API (`/v1`)** | `1.0.0` | **Active / Current** | None | Continuous |
| **Product MCP Server (`/mcp`)** | `2024-11-05` | **Active / Current** | None | Continuous |
| **Docs MCP Server (`/docs/mcp`)** | `2024-11-05` | **Active / Current** | None | Continuous |
| **Sandbox API (`https://sandbox.gaapx.ai/v1`)** | `1.0.0` | **Active / Current** | None | Continuous |

---

## 5. Migration Support

For assistance with migrating legacy endpoints or updating SDK versions:
- Review the [OpenAPI 3.1 Specification](/openapi.json)
- Check [Official Multi-Language SDKs](/docs/integrations/sdks)
- Reach out to developer support at [support@gaapx.ai](mailto:support@gaapx.ai)