Last Updated: 3/11/2026

API Versioning Strategy

Overview

Box introduced API versioning in 2025 to provide a more predictable and stable experience for developers. This document explains how versioning works in the Box OpenAPI specification.

Why Versioning?

API versioning allows Box to:

Introduce breaking changes without disrupting existing integrations
Evolve the API to support new features and improvements
Provide stability with clear deprecation timelines
Maintain backward compatibility for older versions

Version Format

Box uses calendar versioning with the format YYYY.N:

YYYY: The year the version was released (e.g., 2025)
N: The sequential release number within that year (e.g., 0, 1, 2)

Examples

2025.0 - First version released in 2025
2025.1 - Second version released in 2025
2026.0 - First version released in 2026

Specification Files

Versioned specifications are stored in the openapi directory:


openapi/
├── openapi.json              # Pre-versioning API (legacy)
├── openapi-v2025.0.json      # Version 2025.0
├── openapi-v2025.1.json      # Version 2025.1 (future)
└── openapi-v2026.0.json      # Version 2026.0 (future)

Legacy Specification

The openapi.json file in the root directory contains the API specification from before versioning was introduced. This file is maintained for backward compatibility but is no longer actively updated with new features.

Using Versioned APIs

Specifying a Version

To use a specific API version, include the Box-Version header in your requests:


GET /files/12345 HTTP/1.1
Host: api.box.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Box-Version: 2025.0

Default Version

If you don’t specify a version header, Box will use the latest stable version. However, we strongly recommend always specifying a version to ensure consistent behavior.

Version in Client SDKs

When generating client SDKs, use the appropriate versioned specification:


# Generate SDK for version 2025.0
openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/box/box-openapi/main/openapi/openapi-v2025.0.json \
  -g python \
  -o ./box-python-sdk-v2025.0

Version Lifecycle

1. Development

New features and breaking changes are developed
Specification is updated in a development branch
Changes are reviewed and tested

2. Release

New version is published to the main branch
Specification file is added to the openapi directory
Release notes and migration guide are published
Developer documentation is updated

3. Active Support

Bug fixes and security updates are applied
Minor, non-breaking improvements may be added
Version is fully supported and recommended for production use

4. Deprecation Notice

At least 6 months before end-of-life
Deprecation notice is published
Migration guide to newer version is provided
Developers are encouraged to upgrade

5. End-of-Life

Version is no longer supported
No bug fixes or security updates
API may continue to work but is not guaranteed
Minimum 12 months of support from release

Breaking vs. Non-Breaking Changes

Breaking Changes (Require New Version)

Removing an endpoint
Removing a request parameter
Removing a response field
Changing a parameter from optional to required
Changing the data type of a field
Changing authentication requirements
Changing error response format

Non-Breaking Changes (Can Be Added to Existing Version)

Adding a new endpoint
Adding an optional parameter
Adding a new response field
Adding a new error code
Deprecating a field (with continued support)
Improving documentation

Migration Guide

Preparing for a New Version

Review the changelog
- Read the release notes for the new version
- Identify breaking changes that affect your integration

Download the new specification


curl -O https://raw.githubusercontent.com/box/box-openapi/main/openapi/openapi-v2025.1.json

Compare specifications


# Use a diff tool to compare versions
diff openapi-v2025.0.json openapi-v2025.1.json

Update your code
- Regenerate client SDKs if using code generation
- Update API calls to match new schemas
- Handle new error codes
- Update tests
Test thoroughly
- Test all API integrations
- Validate request and response schemas
- Test error handling

Deploy with version header


# Python example
headers = {
    'Authorization': f'Bearer {access_token}',
    'Box-Version': '2025.1'
}
response = requests.get('https://api.box.com/2.0/files/12345', headers=headers)

Gradual Migration

You can migrate gradually by:

Testing in development with the new version
Running parallel versions in staging
Migrating one service at a time in production
Monitoring for issues after each migration step

Version Support Timeline

Version	Release Date	Deprecation Notice	End-of-Life
2025.0	Jan 2025	Jan 2026 (est.)	Jul 2026 (est.)
2025.1	Jun 2025 (est.)	Jun 2026 (est.)	Dec 2026 (est.)

Timeline is subject to change. Official dates will be announced in release notes.

Changelog

Version 2025.0 (January 2025)

New Features:

Initial versioned release
All pre-2025 API endpoints included
Standardized error responses
Enhanced metadata support

Breaking Changes:

None (first versioned release)

Deprecations:

Legacy unversioned API (see openapi.json in root)

Best Practices

For Developers

Always specify the version header in production code
Pin to a specific version rather than using “latest”
Monitor deprecation notices by watching this repository
Plan migrations early when deprecation is announced
Test new versions in development before upgrading
Keep dependencies updated (SDKs, tools)

For CI/CD Pipelines

Validate against the correct specification version


# Example: validate API responses
newman run postman_collection.json \
  --environment production.json \
  --global-var "box_version=2025.0"

Run tests against multiple versions during migration
Use version-specific test fixtures
Monitor API version in logs and metrics

Getting Help

Questions About Versioning

Read the Box API Versioning Strategy Guide
Check the Box Developer Forum
Review release notes

Reporting Issues

Specification errors: Open an issue
API bugs: Contact Box Developer Support
Migration help: Post in the Developer Forum