Versioning#
API Versioning at Workiva#
We have shifted to a unified API with date-based versioning to allow Workiva and its customers to reliably connect to the Workiva Platform using an API without breaking existing integrations. The unified Workiva API is versioned by release date, with the name following a YYYY-MM-DD pattern, provided as the “X-Version” header value. For example, an API version named “1970-01-01” would have been released on January 1st, 1970.
Each major release of the Platform APIs, such as version 2026-01-01, includes changes that are not backwards-compatible with previous releases. Upgrading to a new major release can require updates to existing code, scripts, integrations, Chains, etc.
Each major release of the Platform APIs will be supported as “generally available” until a new release renders it outdated, at which time that release will be marked as “deprecated”.
Once an API version is considered deprecated, it will be supported for 3 years, after which it will sunset and shut off.
There will be two release windows per year for major versions that aren’t backwards-compatible, Spring (April) and Fall (October).
In the event that there aren’t backwards-incompatible changes in the release candidate, there will be no major release in that window.
New, backwards-compatible features to the Platform API will be shipped as part of the API Version that is the most current at the time of release. These changes will be documented in the Changelog for that version of the API. New features will not be retroactively added to previous versions of the API.
In order to target a specific version of the Platform APIs going forward you will need to indicate the version by sending a version header (“X-Version: 2026-01-01”, for example).
By default, requests to the Platform API that do not include a version header will be routed to the 2022-01-01 version until that version is sunset in 2029. At that time, version headers will be required to access the Platform API.
We highly recommend using a single version of the API at a time within integrations, Chains, Scripts, etc. Workiva does not guarantee that mixing and matching multiple API versions will work as expected or desired.
Example 1: A Chain is comprised of commands that all make API calls against the 2022-01-01 version - This is recommended Example 2: A Chain is comprised of commands that are using version 2022-01-01 and other commands that are using version 2026-01-01 - This is not recommended
Breaking changes#
Changes that significantly alter the API functionality (such as feature breaking) will only be released in new date-based API versions. Examples of this sort of change include:
Endpoint/Operation Changes
Removing entire endpoints or operations
Parameter Changes
Removing or renaming parameters, including changes to parameter names
Adding new parameters that are required
Changing previously optional parameters to required
Modifying the type of existing parameters
Introducing new validation rules for existing parameters
Object/Response Changes
Removing or renaming object properties or response fields
Changing the type of response fields
Removing values from enums
Renaming or removing enum values
Other Breaking Changes
Modifying authentication or authorization requirements
Additive (non-breaking) changes#
Additive changes may be provided to any version currently in support. These are changes that shouldn’t break active integrations. Examples of this sort of change include:
Endpoint/Operation Additions
Adding new endpoints or operations
Parameter & Header Additions
Including new optional parameters
Introducing additional optional request headers
Response Additions
Adding new optional fields to responses
Adding new response headers
Enum Additions
Extending enums with additional values
FAQ#
Q: Where did the previous APIs (platform-v1, admin-v1, prototype-platform, prototype-admin, iam-v1, and spreadsheets-v1 APIs) go?
A: All of these APIs have been rolled into version 2022-01-01, along with their documentation. We now refer to this as our “default” version because if a date-based header is not supplied, or is invalid, the call will be handled as if it had supplied a “2022-01-01” version header. These APIs and 2022-01-01 are functionally equivalent. The chains and wdata APIs and their documentation remain unchanged.
Q: How do I view documentation for a particular version?
A: The drop-down menu in the top left-hand corner lets you select the version whose documentation you want to read.
Q: Why is the new date-based version named 2022-01-01? That date was years ago!
A: Workiva has had long-standing functionality that we needed to represent within the framework of our new versioning strategy. The date 2022-01-01 was arbitrarily chosen as the rough date at which Workiva API functionality began to be delivered to the public. Going forward, date-based version names will correspond to their actual release dates.
Q: How do I reference a specific version?
To specify a specific API version, add -H 'X-Version: <version_id>' to your curl request.
Example:
curl -H "X-Version: 2026-01-01" https://api.app.wdesk.com/files
Q: What if I don’t provide a date-based version header?
Calls with no version header default to version 2022-01-01. Version 2022-01-01 is functionally equivalent to our previous platform-v1, admin-v1, prototype-platform, prototype-admin, iam-v1, and spreadsheets-v1 APIs.