> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stora.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning

> Understand Stora API versions, compatibility guarantees, deprecation timelines, and how to migrate.

Stora uses dated API versions to let you plan upgrades without unexpected changes to your integration. A version defines the contract for versioned REST API resource requests, responses, and webhook payloads.

<Note>
  The current API version is `2025-09`. Review its [OpenAPI specification](/2025-09/openapi.json) or the [changelog](/2025-09/guides/changelog).
</Note>

## How API versions work

Versioned resource endpoints use the `YYYY-MM` format in the request path:

```text theme={null}
https://public-api.stora.co/2025-09/sites
```

For resource endpoints, the path determines the version used for API requests and responses. OAuth 2 token endpoints under `/oauth2/` are not date-versioned. Webhook endpoints also store an API version, which determines the structure of their payloads. See [Webhooks](/2025-09/guides/webhooks) for setup details.

## Compatibility within a version

Stora does not introduce breaking changes within a published API version. A breaking change requires a new dated version.

We may make backward-compatible changes within a version, including:

* Adding an endpoint
* Adding an optional request field
* Adding a response field
* Deprecating a field while keeping it available
* Fixing behavior so it matches the documented contract

Your integration should ignore response fields it does not recognize so that compatible additions do not disrupt it.

Changes that require a new version include:

* Removing or renaming an endpoint or field
* Changing a field's type
* Making an optional request field required
* Changing documented behavior in a way that requires client changes

## Version lifecycle

Each API version passes through four lifecycle milestones:

| Milestone                 | Access and support                                                                                                                                                                       |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Current**               | The newest version. It receives backward-compatible features, defect fixes, and security updates.                                                                                        |
| **Deprecated**            | Begins when a successor is released. Standard and Enterprise customers retain access and receive security fixes and fixes for material defects. New features target the current version. |
| **Standard retirement**   | Standard customers retain access through the last calendar day of the sixth month after deprecation. Access ends at 00:00 UTC the following day.                                         |
| **Enterprise retirement** | Enterprise customers retain access through the last calendar day of the twelfth month after deprecation. Access ends at 00:00 UTC the following day.                                     |

Enterprise customers continue to receive maintenance support during months seven through twelve. If Stora releases multiple versions within twelve months, their support windows may overlap.

For example, if a version is deprecated on May 15, 2026, the last supported day is November 30, 2026 for Standard customers and May 31, 2027 for Enterprise customers.

## Supported versions

| Version   | Beta release       | Public release    | Status  | Standard last supported day | Enterprise last supported day | Migration guide |
| --------- | ------------------ | ----------------- | ------- | --------------------------- | ----------------------------- | --------------- |
| `2025-09` | September 30, 2025 | December 16, 2025 | Current | —                           | —                             | —               |

The current version has no scheduled retirement date. When we release a successor, we add separate Standard and Enterprise last supported days and link its dedicated migration guide.

## Deprecation notifications

When Stora releases a new API version, we publish the previous version's deprecation date, Standard last supported day, Enterprise last supported day, and migration guide:

* On this page
* In the [changelog](/2025-09/guides/changelog)
* By email to developers registered in the Developer Portal

<Warning>
  Stora may use a shorter timeline only when necessary to address a serious security, privacy, legal, or regulatory risk. We will communicate the reason and revised timeline as early as possible through the same notification channels.
</Warning>

## Migrate to a new version

We publish a dedicated migration guide with every new API version. The guide explains each breaking change and the work required to move from the previous version. We link it from the supported-versions table, [changelog](/2025-09/guides/changelog), and deprecation email.

<Steps>
  <Step title="Follow the migration guide">
    Work through the release-specific migration guide for your current and target versions.
  </Step>

  <Step title="Review the supporting references">
    Check the [changelog](/2025-09/guides/changelog) and new OpenAPI specification for complete request, response, and webhook schemas.
  </Step>

  <Step title="Update API requests">
    Replace the version in your API request paths and update your integration for the new contract.
  </Step>

  <Step title="Update webhook endpoints">
    Change each webhook endpoint to the new API version so its payloads use the new structure. See [Webhooks](/2025-09/guides/webhooks) for endpoint configuration.
  </Step>

  <Step title="Test and deploy">
    Test affected API calls and webhook handlers, then deploy before your applicable Standard or Enterprise last supported day.
  </Step>
</Steps>