Introducing versioning: A milestone for Box API development
We’re thrilled to announce a significant enhancement to the Box API that will streamline development workflows and foster greater stability and flexibility for developers: versioning.
As part of our ongoing commitment to empowering developers, we’re introducing versioning capabilities for selected API endpoints, ensuring seamless functionality and reliable avenues for feature updates and deprecations.
Why versioning matters
Versioning is pivotal for maintaining compatibility and ensuring that developers can confidently build and scale their applications without worrying about unexpected changes in API behavior.
With versioning, developers gain granular control over the features and functionality they leverage, enabling smoother transitions between different API versions as their applications evolve.
How Box API versioning works
Box API supports versioning in both URL path and header. Developers can specify the desired API version in their requests, ensuring that their applications interact with the intended version of the API.
Default versions are specified in the URL, while the Box-Version header allows for explicit version declaration, offering flexibility and control over API interactions.
For example if there is a significant change to an API endpoint, e.g. https://upload.box.com/api/2.0/files/content, a new endpoint will be provided such as https://upload.box.com/api/3.0/files/content. If your app call a non existing version in the URL, it will return a HTTP 404 — Not found.
However different versions within the default endpoints are also possible using a new header called Box-Version. The following example will list all the sign requests using the 2025.0 endpoint version:
curl --location 'https://api.box.com/2.0/sign_requests' \
--header 'Box-Version: 2025.0' \
--header 'Authorization: Bearer <>If a Box-Version header specifies a non existing version, the API returns a HTTP 404 — Not found error.
If a Box-Version header specifies a deprecated version, the API returns a Deprecation header.
Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecatedYour application should monitor these deprecation headers, allowing you to plan the update.
Release schedule and naming convention
We follow a structured release schedule, and new breaking changes can be introduced to certain endpoints at maximum once per year. If an endpoint has a new version, all the HTTP methods (GET/POST/PUT) are affected.
Our naming convention reflects the calendar year of release, with incremental versioning for security or privacy updates.
For example, if a new version of the sign requests endpoint is released in 2025, it will be named 2025.0. If security issues need addressing in the previously released version 2025.0 of sign requests, the new version will be labeled 2025.1, and so on.
Each stable version is supported for a minimum of 12 months, providing developers with ample time to adapt and transition to newer versions.
When a new version is release it immediately deprecates the previous version, which means no new features will be added.
Deprecated versions will continue to work until Box decides to retire them. This End Of Life (EOL) is declared 24 months in advance.
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.
Please consult our guide to see what is considered a breaking change.
SDK Versioning
This versioning strategy will only be applied to the Next Gen SDKs. Classic SDKs will not be maintained.
Both stable and deprecated versions of the API will be supported by the Next Gen SDKs. When a new version is introduced it is tagged with the version, and included in the corresponding manager, alog side any deprecated versions. When a version is EOL, it is removed from the corresponding manager.
For example, FileManager, updateFileByID initial state:
class FilesManager {
async updateFileById(
fileId: string,
requestBody: UpdateFileByIdRequestBody,
queryParams: UpdateFileByIdQueryParams,
headers: UpdateFileByIdHeaders
): Promise < FileFull > {}
}A new version is introduce, deprecating the original version:
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> {}
}When the original version end of life is declared:
class FilesManager {
async updateFileById_2025_0(
fileId: string,
requestBody: UpdateFileByIdRequestBody_2025_0,
queryParams: UpdateFileByIdQueryParams_2025_0,
headers: UpdateFileByIdHeaders_2025_0
): Promise < FileFull_2025_0 > {}
}Conclusion
Versioning marks a significant milestone in the evolution of the Box API, offering developers enhanced control, stability, and flexibility. We’re committed to continuously improving the developer experience, and versioning is a key step towards that goal. We look forward to your continued collaboration as we embark on this journey together.
For in depth documentation about Box API versioning please consult the API Versioning Strategy guide.
Feedback and collaboration
We value your feedback and insights as we roll out versioning for the Box API. Your input is instrumental in shaping our versioning strategy and ensuring that it meets the needs of our developer community. We invite you to share your thoughts, suggestions, and experiences with versioning, helping us refine and improve this essential aspect of the Box API.
Drop us a line at forum.box.com
