API Versioning at Workiva
Application Programming Interface (API) versioning is the critical practice of assigning unique identifiers to different iterations of an API’s design to manage and communicate changes effectively. Its primary purpose is to maintain backward compatibility, ensuring that scripts and applications relying on an older version do not break when a new API version is released. This stability allows API providers to introduce major updates, bug fixes, and new features without disrupting existing users, granting consumers the time and control needed to migrate their systems when they are ready. Ultimately, proper API versioning promotes a reliable, scalable, and professional development ecosystem.
2026-01-01 API Version Release
In January 2026 Workiva will release a new API version, 2026-01-01. This new version introduces significant improvements across multiple areas, including improved consistency, new functionality, and deprecation of legacy features. The benefits of upgrading to the 2026-01-01 version include continued compatibility with the latest Workiva Platform features enhanced security, improved performance, and the ability to leverage new features.
For additional information on the new API version, see the Workiva API 2026-01-01 Upgrade Guide.
Deprecation of 2022-01-01 API Version
With the release of the 2026-01-01 version, the older 2022-01-01 version will enter its deprecation phase. Support for this older version will continue until its sunset in January 2029, and support for the 2022-01-01 Prototype endpoints will end in January 2027.
Note: Most Prototype endpoints in the 2022-01-01 version have been promoted to General Availability (GA) in the 2026-01-01 version.
| Version | Status | Endpoint Type | Sunset Date |
|---|---|---|---|
| 2026-01-01 | General Availability (GA) | All | N/A (Current) |
| 2022-01-01 | Deprecated | Prototype | January 2027 |
| 2022-01-01 | Deprecated | GA | January 2029 |
Comparing API Versions
When a new version is released, the API documentation for that version on the Workiva Developers Hub includes a Changelog section that includes detailed documentation about API changes in that version. The 2026-01-01 version will have a 2026-01-01 Upgrade Guide section with a full walkthrough of the changes in that version.
In addition, there are many open source tools available to run a comparison on two different API versions. These types of tools allow for rapid and detailed comparisons of version changes. The open source tool oasdiff has a web-based Diff Calculator that allows you to upload two API version config files (oas.yaml) and run a comparison for breaking changes, changelogs, or a raw diff. It can output results in text, yaml, json, html, and markdown.
Reference a Specific API Version
Workiva APIs leverage the X-Version header to specify which API version to use. If the X-Version header is not passed the version defaults to the deprecated 2022-01-01 version.
Note: After January 2029 the X-Version header will be required and all API calls without it will fail.
To specify the version in an API request via Python, include the key/value pair in the headers for each API request. For example: headers = {‘X-Version’: ‘2026-01-01’}
Currently you can specify either 2026-01-01 or 2022-01-01.
Since there are many breaking changes in the 2026-01-01 version, it is critical to ensure both the X-Version header is set for the applicable version and that the API endpoint URL path and parameters match the required structure of that version. In addition, it is important to understand the response format of the API call and any potential differences of that format between versions.
Examples
GET Request Example
Here an example of using a GET request in the Retrieve a List of Spreadsheets endpoint for both the 2026-01-01 and the 2022-01-01 versions (these examples include the bearer token as the token variable for obfuscation purposes in this article).
2026-01-01 version
# 2026-01-01 version
# note the X-Version header and the requests URL
headers = {
'Accept': 'application/json',
'Authorization': token,
'X-Version': '2026-01-01',
}
resp = requests.get(
'https://api.app.wdesk.com/spreadsheets',
headers = headers,
)2022-01-01 version
# 2022-01-01 version
# note the X-Version header and the requests URL
headers = {
'Accept': 'application/json',
'Authorization': token,
'X-Version': '2022-01-01',
}
resp = requests.get(
'https://api.app.wdesk.com/platform/v1/spreadsheets',
headers = headers,
)
PATCH Request Example
Below is an example of using a PATCH request in the Partially Update a Single Section endpoint for both the 2026-01-01 and the 2022-01-01 versions (these examples include the bearer token as the token variable in this article for obfuscation purposes).
2026-01-01 version
# 2026-01-01 version
# note the X-Version header and the requests URL
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization':token,
'X-Version': '2026-01-01',
}
patch_op = [
{
"op": "replace",
"path": "/name",
"value": "My New Section Name"
}
]
resp = requests.patch
(
https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}',
json = patch_op,
headers = headers,
)
2022-01-01 version
# 2022-01-01 version
# note the X-Version header and the requests URL
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': token,
'X-Version': '2022-01-01',
}
patch_op = [
{
"op": "replace",
"path": "/name",
"value": "My New Section Name"
}
]
resp = requests.patch(
f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}',
json = patch_op,
headers = headers,
)
Tip: In addition to ensuring the URL path and parameters structure match the applicable API version, be sure to check the documentation for details about the available parameter options.
For example, in the Partially Update a Single Section example above, in the 2022-01-01 version there are three available path options ( /name , /index , /parent ), but in the 2026-01-01 version there are over thirty available path options.
Best Practices for Scripting and API Versioning
While the specific API version you require may depend on the status of active scripts and applications, timelines for upgrading to the new API version, or other factors, below are some best practices related to scripting and API versioning.
Always Specify the API Version
Never rely on an API provider’s default version. Explicitly specify the version in every API call. By explicitly specifying the version you are in control of which version the script or application runs.
Centralize the Version Constant
Define the API version as a single, easily locatable constant or configuration variable at the top of your script or in a separate configuration file. This reliably streamlines troubleshooting and improves maintainability. Example:
# config.py or at the top of the main script
API_VERSION = '2026-01-01'
# in a requests call
headers = {
'Accept': 'application/json',
'Authorization': token,
'X-Version': API_VERSION,
}
resp = requests.get(
'https://api.app.wdesk.com/spreadsheets',
headers = headers,
)
Avoid Mixing API Versions
Do not attempt to mix API versions within a single script or application. All API calls within a single script or application should reference the same Workiva API version (e.g. all API calls should use the “2026-01-01” version). Mixing versions complicates debugging, request schemas, and response formats, making the script’s behavior unpredictable and maintenance more complicated.
Isolate API Interaction Logic
Create a dedicated module or set of functions (often called a “wrapper” or “client”) that handles all communication with the external API. This pattern separates the “business logic” of your script from the “API communication logic.” If the API changes (e.g. endpoint URL or request/response structure changes in a new API version), only the wrapper functions need to be updated, not the entire script(s).
Handle Deprecated Endpoints and Parameters Gracefully
When migrating from an old API version to a new one, anticipate that endpoints and parameters may be renamed or removed. Ensure that your script includes robust error handling and logging, as this supports best practices for scripting development as well as increasing the probability that version-related errors will be caught and logged.
For additional information on scripting best practices, see the Workiva Scripting: Development Best Practices article.
Monitor and Plan for Deprecation
Workiva is shifting to providing two release windows per year for new major versions; Spring and Fall. In the event that there are no breaking changes when a release date approaches and the release candidate for that period is empty, Workiva will not publish a new version of the API at that time.
We recommend that you actively track the Workiva API Developer Hub website, subscribe to Workiva Release Notes, and follow the published release and deprecation schedules. Scripts using a deprecated API version will eventually break. Knowing the sunset (end-of-life) date for an API version allows you to schedule the necessary upgrade work before the sunset date.
Script Migration and Validation
To ensure seamless API version migration, establish a parallel testing strategy: copy the existing production script, modify only the copy to target the new API version (including any required changes to headers, URL path, and/or request/response structure), and then test both the old and new scripts to compare and verify functionality and output.
By running them side-by-side in a controlled environment, you can use the stable older script as the standard to monitor and verify that the functionality and result produced by the new script are identical before fully switching over to the new version and deprecating the old version.