API Versioning Strategy

Box provides versioning capabilities for selected API endpoints. The version control system guarantees seamless functioning of existing endpoint versions, even if Box introduces new ones.

API versioning empowers Box to continually enhance its platform, while also offering third-party developers a reliable avenue for feature updates and deprecations.

How Box API versioning works

The default version of the API used in any requests is specified in the URL of the endpoint you call. An example flow looks like this:

1. When calling the upload endpoint without any version header specified, you hit the 2.0 version defined in the URL.

2. Box API processes the Box-Version header which should:

   • contain a valid version name, that is Box-Version: 2025.0
   • be directed at https://api.box.com/2.0/files/:file_id/metadata.
3. If the provided version is correct, a response is sent back to the client. The response also contains the Box-Version header if it was provided in the request. By default, this header is not present in the response. If the version is wrong, an error with the HTTP code 400 is returned to the client.

If there is a significant change to API behavior, the new endpoint will be exposed under the new URL. For example, https://upload.box.com/api/2.0/files/content supports a multipart content type when uploading files to Box. If the new version of this API stops supporting this content type, it will be released under a new URL https://upload.box.com/api/3.0/files/content.

Release schedule and naming convention

Box can introduce a new breaking change to certain endpoints once per year. An endpoint encompasses all supported HTTP methods within a specific API root. For example, the Sign Request endpoints include:

Introducing a new version of the sign request endpoint means that all paths and HTTP methods listed above will support it. You can find comprehensive information about the endpoint version in the Box API Reference.

Naming convention

New API versions are labeled according to the calendar year of their release. For example, if a new version of the Sign Requests endpoint is released in 2025, it will be named 2025.0.

Box can issue a new breaking change to API endpoints once per year, reserving the right to release an additional breaking change to address security or privacy concerns. In such cases, the new version will be incremented by one in the suffix. For example, if security issues need addressing in the previously released version 2025.0 of Sign Requests, the new version will be labeled 2025.1.

Each stable version is supported for a minimum of 12 months. This means that when a new version is released, the previous version becomes deprecated and will be available for use, but no new features will be added. It also means, that a new version cannot be released sooner than every 12 months.

We strongly recommend updating your apps to make requests to the latest stable API version. However, if your app uses a stable version that is no longer supported, then you will get a response with an HTTP error code 404 - Not Found. For details, see Versioning Errors.

If your request doesn't include a version, then the API defaults to the V2 Box API version. However, we do not recommend relying on this behavior for adopting deprecated changes. As you update your app, you should specify the API version with every request. By making your app version-aware, you anchor your code to a specific set of features that are guaranteed to behave in the same way for the supported timeframe.

Calling an API version

Box API versions are explicitly declared in the Box-Version header that your app makes requests to. For example:

curl --location 'https://api.box.com/2.0/sign_requests' \
--header 'Box-Version: 2025.0' \
--header 'Authorization: Bearer …

The client gets a list of all created sign requests and asks for version 2025.0. There are several supported versions of the APIs available, and you specify the version that you want to use with the Box-Version header. There are three types of API versions: stable, deprecated, and unstable.

Versioning errors

Calling an incorrect API version in the URL

Box documentation specifies API URLs. For instance, the Sign Requests endpoints are accessed via: https://api.box.com/2.0/sign_requests/. If a customer mistakenly makes a call to an incorrect version, such as https://api.box.com/3.0/sign_requests/, the response returns an HTTP error code 404 - Not Found error.

Calling a deprecated API

When a customer uses an API version that Box has marked as deprecated, the API will respond as usual. However, it will append a Deprecation header, stating the deprecation date, for example:

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

Customers should monitor API responses and take note when this header appears, signaling the need to plan for the transition to a new API version.

Calling a nonexistent version

If a customer attempts to use an outdated API version, such as 2023.0, which has reached its end-of-life, the response will return an HTTP error code 404 - Not Found. See Calling an incorrect API version in the URL for more information.

How Box SDK versioning works

The versioning strategy is only applied to next generation generated SDKs. Box SDKs support the All Versions In SDK approach. This means that every release of SDK provides access to all endpoints in any version which is currently live. All generated SDKs use manager's approach - they group all endpoints with the same domain in one manager. For example FolderManager contains methods to: create_folder, get_folder_by_id, update_folder_by_id, delete_folder_by_id, get_folder_items and copy_folder.This division is done based on the value of x-box-tag field, which is assigned to each method in Public API Service specification. It mostly corresponds to the root of the endpoint URL, but not necessarily. For example: FolderManager contains methods with https://api.box.com/2.0/folders root URL, but the same base URL is also used in some methods of SharedLinkFoldersManager. References to all managers are stored under one Box Client object.

See an example of the endpoint's lifecycle:

1. Initial state (only one version is available).

   class FilesManager {
   async updateFileById(
   fileId: string,
   requestBody: UpdateFileByIdRequestBody,
   queryParams: UpdateFileByIdQueryParams,
   headers: UpdateFileByIdHeaders
   ): Promise < FileFull > {}
   }
   

2. A new v2025_0 version of the endpoint is introduced (previous version is deprecated).

   The SDK introduces a new method for each new version of an endpoint. These methods are stored in the same manager as the old ones, but their names and corresponding classes are suffixed with the version number. The old method is deprecated with a notice indicating the minimal maintenance date – this will be the date when the endpoint will be considered for end-of-life status.

   class FilesManager {
   /**
    * @deprecated This endpoint will be EOL'ed after 05-2026.
    */
   async updateFileById(
      fileId: string,
   requestBody: UpdateFileByIdRequestBody,
   queryParams: UpdateFileByIdQueryParams,
   headers: UpdateFileByIdHeaders
   ): Promise<FileFull> {}
   
   async updateFileById_2025_0(
   fileId: string,
   requestBody: UpdateFileByIdRequestBody_2025_0,
   queryParams: UpdateFileByIdQueryParams_2025_0,
   headers: UpdateFileByIdHeaders_2025_0
   ): Promise<FileFull_2025_0> {}
   }
   

3. The API endpoint is marked as End-of-Life (EOL)

   The SDK releases a breaking change release with removed end-of-life (EOL) endpoints. Ideally, we should group the end-of-life dates for all endpoints into one date per quarter to avoid releasing numerous new major versions of SDKs.

   class FilesManager {
   async updateFileById_2025_0(
   fileId: string,
   requestBody: UpdateFileByIdRequestBody_2025_0,
   queryParams: UpdateFileByIdQueryParams_2025_0,
   headers: UpdateFileByIdHeaders_2025_0
   ): Promise < FileFull_2025_0 > {}
   }
   

Breaking vs non-breaking changes

Breaking changes in the Box API occur within versioned releases, typically accompanied by a new major API version. Minor adjustments, which do not disrupt existing functionality, can be integrated into an existing API version. The following table offers illustrations of both breaking and non-breaking changes.

Support policy and deprecation information

When new versions of the Box APIs and Box SDKs are released, earlier versions will be retired. Box marks a version as deprecated at least 24 months before retiring it. In other words, a deprecated version cannot become end-of-life sooner than after 24 months. Similarly, for individual APIs that are generally available (GA), Box declares an API as deprecated at least 24 months in advance of removing it from the GA version.

When we increment the major version of the API (for example, from 2024.0 to 2025.0), we're announcing that the current version (in this example, 2024.0) is immediately deprecated and we'll no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.

When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. In some cases, we'll announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated.

When customer calls deprecated API endpoint, the response will contain a header:

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

The date tells clients when this version was marked as deprecated.

Versioning considerations

When building your request, consider that:

• If you do not specify a version, the service returns a default version that may not be the latest one.
• When the version header is missing, the default resource version is determined by the version in the URL.
• When the version header is specified, but the requested version is unavailable, then the response will return an HTTP error code 404 - Not Found.

When Box deprecates a resource or a property of a resource in the API, the change is communicated in one or more of the following ways:

• Calls that include the deprecated behavior return the response header Box-API-Deprecated-Reason and a link to get more information:

Box-Version: 2023.0
Deprecation: version="version", date="date"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

• A notice about the deprecation is posted in the developer changelog.
• The API reference is updated to identify the affected resource and any action you need to take.
• If there is an imminent backwards-incompatible change that affects your app, then the contact email for your app might be contacted about the deprecation.

Additional resources

• API reference