2026-01-01 Upgrade Guide

This guide will walk you through the changes introduced in the 2026-01-01 version of the API and help you update your integration accordingly. Please refer to our versioning documentation for more information on how date-based versioning works.

For now, the 2022-01-01 version of the API will stay available. Any removal of this version will come with advance notice.

Breaking Changes

The following breaking changes have been introduced in the 2026-01-01 version:

Path Changes

All paths have been changed to remove these prefixes:

• /platform/v1/

• /admin/v1/

• /prototype-platform/

• /prototype-admin/

• /iam/v1/

Before we introduced date-based versioning, these segments were used to indicate different API versions. With the new date-based versioning system, we have unified the paths within a single version.

Migration Steps

1. Review your existing API calls

2. Remove these prefixes from the paths

Examples

Get Authorization Token (2022-01-01):

curl https://api.app.wdesk.com/iam/v1/oauth2/token -X POST -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' -d "client_id=<client-id>&client_secret=<client-secret>&grant_type=client_credentials"

Get Authorization Token (2026-01-01):

curl https://api.app.wdesk.com/oauth2/token -X POST -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' -d "client_id=<client-id>&client_secret=<client-secret>&grant_type=client_credentials" -H "X-Version: 2026-01-01"

Get Documents (2022-01-01):

curl https://api.app.wdesk.com/platform/v1/documents -H "Authorization: Bearer <token>"

Get Documents (2026-01-01):

curl https://api.app.wdesk.com/documents -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Prototype Endpoints Removed

We have included some prototype functionality in the 2026-01-01 version. Check out the New Features section below for more details. All other prototype endpoints have been removed. Going forward, we will be creating Preview versions of the Public API for new features that with the intention of promoting their functionality to the stable version after a period of testing and feedback. For now, we’re leaving the existing prototype endpoints in the 2022-01-01 version for backward compatibility.

Migration Steps

1. Identify any prototype endpoints you are using

2. Transition to the stable endpoints in the 2026-01-01 version where available

3. If no stable endpoint exists, look out for upcoming Preview versions of the API for new features

Removed Legacy Spreadsheets Endpoints

All endpoints under the /spreadsheets/v1 path have been removed. Please migrate to the endpoints that were previously under the /platform/v1/spreadsheets path.

Migration Steps

1. Identify calls to /spreadsheets/v1 endpoints

2. Replace with equivalent /spreadsheets endpoints

Examples

Get Spreadsheet by ID (2022-01-01):

curl https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/{spreadsheetId} -H "Authorization: Bearer <token>"

Get Spreadsheet by ID (2026-01-01):

curl https://api.app.wdesk.com/spreadsheets/{spreadsheetId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Removed GET /platform/v1/graph/reports/{reportId}/csv

This endpoint has been removed in favor of using the async csv export endpoint. Initiate a graph report export has been available in 2022-01-01 for a long time and provides better performance for large reports. This same endpoint is also available in 2026-01-01.

Migration Steps

1. Replace calls to GET /platform/v1/graph/reports/{reportId}/csv with calls to POST /graph/reports/{reportId}/export to initiate the export

Examples

Get Graph Report CSV (2022-01-01):

curl https://api.app.wdesk.com/platform/v1/graph/reports/{reportId}/csv -H "Authorization: Bearer <token>"

Initiate Graph Report Export (2026-01-01):

curl -X POST https://api.app.wdesk.com/graph/reports/{reportId}/export -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01" -d '{
  "format": "csv"
}'

# Poll the operation URL returned in the Location header
curl https://api.app.wdesk.com/operations/{operationId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

# Once the operation is complete, download the CSV from the resourceUrl in the operation result
curl <resourceUrl> -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01" --output report.csv

Removed Support for Trailing Slashes in Paths

Previously, the API accepted paths with trailing slashes (e.g., /documents/) as equivalent to paths without them (e.g., /documents). In the 2026-01-01 version, trailing slashes are no longer accepted and will result in a 404 error. This change standardizes our URL patterns and improves routing consistency.

Migration Steps

1. Review your existing API calls

2. Remove any trailing slashes from endpoint paths

3. Test your updated requests

Examples

Get Documents (2022-01-01 - with trailing slash):

curl https://api.app.wdesk.com/platform/v1/documents/ -H "Authorization: Bearer <token>"

Get Documents (2026-01-01 - without trailing slash):

curl https://api.app.wdesk.com/documents -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Get Document by ID (2022-01-01 - with trailing slash):

curl https://api.app.wdesk.com/platform/v1/documents/{documentId}/ -H "Authorization: Bearer <token>"

Get Document by ID (2026-01-01 - without trailing slash):

curl https://api.app.wdesk.com/documents/{documentId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

GET /organizations/{organizationId}/orgReportUsers requires organization:read scope

This endpoint now requires the organization:read scope to be present in your API token’s authorization.

Migration Steps

1. Review your API token scopes

• If the grant is linked to your user, you can see the scopes under your user profile

• Organization Admins can view all associated API grants under the Security Tab in the Organization Admin view

• Organization Admins can also update the scopes for existing grants

1. Ensure your token includes the organization:read scope

Examples

Get Organization Report Users (2022-01-01 - no scope requirement):

curl https://api.app.wdesk.com/admin/v1/organizations/{organizationId}/orgReportUsers -H "Authorization: Bearer <token>"

Get Organization Report Users (2026-01-01 - requires organization:read scope):

curl https://api.app.wdesk.com/organizations/{organizationId}/orgReportUsers -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Removed GET /platform/v1/users

This endpoint has been removed in favor of the organization users endpoint, which provides better filtering and organization of user data. If you are specifically looking for a list of workspace members, please use the GET /organizations/{organizationId}/workspaces/{workspaceId}/memberships endpoint instead.

Migration Steps

1. Identify calls to GET /platform/v1/users

2. Replace with GET /organizations/{organizationId}/users

3. Update your authorization to include the organization:read scope

Examples

Get Users (2022-01-01):

curl https://api.app.wdesk.com/platform/v1/users -H "Authorization: Bearer <token>"

Get Organization Users (2026-01-01):

curl https://api.app.wdesk.com/organizations/{organizationId}/users -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Note: The new endpoint is organization-scoped and requires the organization:read scope in your token. You will need to provide the organization ID in the request path.

Removed PUT endpoints for Documents and Spreadsheets

The following PUT endpoints have been removed:

• /documents/{documentId}/sections/{sectionId}

• /files/{fileId}

• /spreadsheets/{spreadsheetId}/sheets/{sheetId}

• /tasks/{taskId}

• /testForms/{testFormId}/testPhases/{testPhaseId}/matrices/{matrixId}/samples/{sampleId}

These endpoints have been removed in favor of using PATCH operations for updates. PATCH requests allow for partial updates and are more explicit about the changes being made. All of the listed endpoints have equivalent PATCH operations available.

Migration Steps

1. Identify calls to the removed PUT endpoints

2. Replace with equivalent PATCH operations

Examples

Update Document Section (2022-01-01 - PUT):

curl -X PUT https://api.app.wdesk.com/platform/v1/files/{fileId} -H "Authorization: Bearer <token>" -d '{
    "kind": "Document",
    "name": "Updated File Name",
}'

Update Document Section (2026-01-01 - PATCH):

curl -X PATCH https://api.app.wdesk.com/files/{fileId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01" -H "Content-Type: application/json" -d '[
    {
        "op": "replace",
        "path": "/name",
        "value": "Updated File Name"
    }
]'

Async PATCH endpoints for Documents and Spreadsheets

PATCH operations on documents, sections, spreadsheets, and sheets are now asynchronous. Previously, these operations returned synchronously with the updated resource. Now they return an operation in the Location header that you can poll to check the status of the update. This change improves performance and reliability when many successive updates are made.

Migration Steps

1. Identify calls to these endpoints:

• PATCH /documents/{documentId}

• PATCH /documents/{documentId}/sections/{sectionId}

• PATCH /spreadsheets/{spreadsheetId}

• PATCH /spreadsheets/{spreadsheetId}/sheets/{sheetId}

1. Poll the operation URL returned in the Location header to check completion status

Examples

Update Document (2022-01-01 - synchronous):

curl -X PATCH https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId} -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '[
    {
        "op": "replace",
        "path": "/name",
        "value": "Updated Section Name"
    }
]'

Update Document (2026-01-01 - asynchronous):

curl -X PATCH https://api.app.wdesk.com/documents/{documentId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01" -H "Content-Type: application/json" -d '[
    {
        "op": "replace",
        "path": "/name",
        "value": "Updated Section Name"
    }
]'

# Poll the operation URL returned in the Location header
curl https://api.app.wdesk.com/operations/{operationId} -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01"

Removed Support for ‘name contains’ filter on GET /files

The ‘name contains’ filter on the GET /files endpoint has been removed due to performance concerns with large datasets.

Migration Steps

1. Identify calls to GET /files that use the ‘name contains’ filter

2. Remove the filter from your requests, otherwise the request will return a 400 Bad Request error

3. Consider replacing this functionality by using the container eq <folder ID> filter to narrow down the search scope

Examples

Get Files with ‘name contains’ filter (2022-01-01):

curl -G https://api.app.wdesk.com/platform/v1/files -H "Authorization: Bearer <token>" --data-urlencode "\$filter=name contains 'Report'"

Get Files without ‘name contains’ filter (2026-01-01):

curl -G https://api.app.wdesk.com/files -H "Authorization: Bearer <token>" -H "X-Version: 2026-01-01" --data-urlencode "\$filter=container eq 'V0ZEYXRhRW50aXR5HkZvbGRlcjpjOGQ4N2EzMWQ2Mzg0MzQ2Yjc2YjA2MjFmNjk3ZjJlYg'"

New Features

We’ve promoted several features from prototype endpoints into the stable 2026-01-01 version of the API. Here are some of the key additions.

Organization and Workspace Admin Endpoints

A suite of APIs that enable the ability to manage users, organizations, and workspaces within the Workiva Platform are now generally available for business critical integrations.

With this additional suite of APIs you can now automate the following scenarios via API and more:

• Create & manage a Workspace

• Create & manage a Workspace Membership

• Create & manage a Group

• Create & manage a new Organization User

• Assign, list & revoke roles for users and memberships

• Retrieve lists of groups, users, roles, memberships, workspaces and organizations

• Retrieve, list, and modify permissions for files, documents, and spreadsheets

Changes From Prototype

Role IDs are now represented as UUIDs instead of stringified integers.

File Management Endpoints

A new suite of endpoints have been released that enable the following use cases to be possible for non-Workiva file types (PDF, PNG, CSV, etc.) or what Workiva calls Supporting Documents:

Import Export

In addition, these types of files will now be represented when a GET Files API call is made, if there are those kinds of files present at the target point of that request. Support for Permissions for these files is also supported via API.

Tasking Endpoints

We’re excited to bring the enhanced Tasking endpoints from prototype to general availability. Previously available on the prototype/platform paths in version 2022-01-01, these endpoints are now production-ready and offer significant improvements to help you build more sophisticated task management workflows.

Key enhancements include:

• Multiple Assignees – Tasks can now be assigned to multiple users simultaneously, enabling better collaboration and workload distribution

• Approval Workflows – New ApprovalSteps provide structured approval processes within tasks, giving you greater control over review and sign-off procedures

• Task Submission – Programmatically submit tasks via the new /tasks/{taskId}/actionSubmission endpoint, streamlining your automation workflows

Sustainability Endpoints

We’re pleased to introduce our new Sustainability endpoints, now promoted from the prototype/platform paths in version 2022-01-01 to general availability. These production-ready endpoints provide comprehensive API access to your sustainability reporting workflows, enabling you to programmatically manage your sustainability programs, topics, metrics, and dimensions.

These endpoints integrate seamlessly with the 2026-01-01 Tasking endpoints. Once your Mertric Value has a task attached to it, the 2026-01-01 Tasking endpoints can be used to programmatically manage your Sustainability Tasks.

FAQ

This FAQ addresses common questions regarding the transition and upgrade process from the 2022-01-01 version of the Workiva Platform APIs to the upcoming 2026-01-01 version.

General Information

What is changing in the Workiva Platform APIs?

The 2026-01-01 version of the Workiva Platform APIs introduces significant improvements across multiple areas, including:

• Improved Consistency and Predictability: Enhanced adherence to RESTful principles for more intuitive resource interactions. Going forward, major versions of the Platform APIs will be supported for 3 years, and there will be two major version releases per year (Spring and Fall)

• New Functionality: Introduction of new endpoints and capabilities, previously only available in Prototype such as

  • User, Workspace, and Organization Management endpoints,

  • Content Endpoints for Documents and Spreadsheets

  • Range Linking endpoints

  • Files Management endpoints

• Deprecation of Legacy Features: Endpoints in the 2022 version of the API are now considered deprecated (more on what that means below)

How do I know if my organization is using Workiva APIs?

The recommended approach to understand if your organization is using our APIs is to check if there are active API grants in any of the Workspaces within your Organization.

There are two ways to achieve this:

• Ideally - an Org Admin or Org Security Admin logs in and uses this documentation to access all workspaces to check if there are active API grants.

• Next best - Individual Workspace Owners or Workspace Security Admins log into each of their workspaces and use this documentation to check for active API grants.

When will the 2026-01-01 Workiva Platform APIs be released?

The 2026-01-01 Workiva Platform APIs are scheduled for General Availability (GA) on January 26, 2026. There will be various features that are additively released to the first 2026-01-01 version as fast-follows. These include Scripting APIs and Chain support for API versioning with commands, nodes and connectors.

How long will the 2022 API version be supported?

The 2022 version of the Workiva Platform APIs will enter a Deprecation Phase upon the GA release of the 2026-01-01 version in January 2026. Sunset for the 2022 version is currently scheduled for January 2029. We strongly recommend completing your migration before the Sunset date.

What is the primary benefit of upgrading?

Upgrading ensures your integrations remain compatible with the latest Workiva Platform features, benefit from enhanced security, experience better performance, and leverage new capabilities not available in the 2022 version.

Does Workiva have a release cadence for major versions of the platform APIs?

Yes, going forward from the 2026-01-01 major release Workiva will have 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, we will not publish a new version of the API at that time.

New versions will only be released during the Spring and Fall window if there are breaking changes required to be made.

Can I mix multiple versions of the APIs in my integration?

Workiva only commits to API functionality within a single major version of the API. We strongly recommend that users do not have multiple versions of our APIs being used simultaneously within a singular integration, script, or chain.

Example; User has a chain composed entirely of endpoints within version 2026-01-01, great that should work and we support that.

As opposed to a user having a chain that makes some API calls to 2022-01-01 and other API calls to 2026-01-01 in the same chain or script, we do NOT guarantee that will work and advise against that.

What is going to happen to the Prototype APIs?

The Prototype APIs will be visually removed from the developer site however they will continue to function normally. Prototype APIs will be supported through January 2027, ensuring users have ample time to transition to the 2026-01-01 version of the API. Going forward, API Previews will replace the Prototype APIs.

What are API Previews?

API Previews are the way that users can give feedback on new APIs that will be promoted to general availability before they’re shipped. API Previews will be short lived (30-60 days) and targeted towards a specific feature set (e.g. there could be an API Preview specifically for Processes APIs). Please ensure that your Organization has signed the Preview Feature Agreement in order to participate in these previews. If you haven’t or aren’t sure if your Organization has signed the agreement please reach out to your CSM.

What does this mean for Workiva Scripting?

Workiva Scripting APIs will remain in Prototype until they are ready to be promoted to general availability later in 2026, at which time they will be shipped into the current major version as additive changes.

The Scripting APIs in Prototype will remain suppressed until the end of January, 2027, when they will be shut down alongside the rest of the Prototype API’s.

Partners and Customers are highly encouraged to upgrade to the 2026-01-01 version of the Scripting APIs when they are generally available as soon as possible.

Users should be able to start sending the version header as part of their python code as soon as they are ready to upgrade to the latest version of the API

Support Articles will be published to our customer facing enablement sites that cover best practices for Scripting and version control with APIs after the release of our January 2026-01-01 version.

What does this mean for Chains?

The Chains APIs are for the time being out of scope of our new version policy and will not be part of this release or change.

Support for making a Chain that utilizes the new version of the Platform API, as well as Connector support for new versions of the Platform API will be coming after the 2026-01-01 version release, some time in 2026.

Users will be able to utilize the 2026-01-01 version of the API through HTTP Request Connector if they build out the command manually.

Chains commands and connectors built on the 2022-01-01 will continue to function as normally and be supported throughout the lifetime of the 2022-01-01 version of the Platform APIs.

Users that are already leveraging the HTTP Request connector to interact with the 2022-01-01 and prototype versions of the APIs will need to update those commands in order to take advantage of features in the 2026-01-01 version if you would like to.

What does this mean for Wdata?

The Wdata APIs are for the time being out of scope of our new version policy and will not be part of this release or change. They will continue to be considered separate from the Platform APIs until otherwise announced.

Technical Migration Details

What are the most significant breaking changes I should prepare for?

Key breaking changes include:

1. Endpoint Path Changes: Many resource paths have been updated for better consistency. For example, a resource previously accessed at /v1/workspaces/{id}/documents might move to /documents/search?workspace_id={id}.

   1. The version of the API being used will no longer be part of the URL schema and is instead indicated at the x-version header level going forward

2. Request/Response Schema Changes: Data models for several resources have been normalized. This means fields may be renamed, relocated, or have different data types (e.g., a field that accepted an integer might now require a string UUID).

Is there a compatibility layer or feature flag for gradual adoption?

No, the 2026-01-01 API is a distinct version. We strongly recommend testing the new endpoints in a dedicated non-production environment. We will maintain the 2022 version in parallel until the sunset date, allowing you to run both versions simultaneously during the transition period.

Where can I find detailed documentation for the 2026-01-01 APIs?

The comprehensive Workiva Developer Portal will host the full OpenAPI Specification and detailed guides for the 2026-01-01 APIs starting with the Public Preview in January 2026.

Are all 2022 API functionalities available in the 2026-01-01 version?

While the vast majority functionalities are retained, some legacy, less-used endpoints from 2022 have been retired. Conversely, several entirely new features are available. We recommend cross-referencing your current usage against the 2026-01-01 API documentation.

Planning and Support

What steps should I take to plan my upgrade?

We recommend the following phased approach:

1. Audit: Identify all current API integrations using the 2022 version. Document the endpoints, methods, and data models currently in use.

   1. In Chains specifically, this would also involve auditing your connections and command usage as well.

2. Review: Compare your audited usage against the 2026-01-01 API documentation to identify necessary code changes.

3. Test: Begin development and rigorous testing. Focus on critical path integrations first.

4. Deploy: Schedule the deployment of the upgraded integrations into your production environment well before the January 2029 Sunset date. Prototype APIs will be shut down at the end of January 2027, before the 2029 sunset date of the 2022 version.

What resources are available to help with the migration?

• Migration Guide: A dedicated “2022 to 2026 Migration Guide” detailing all breaking changes and recommended replacements is available here.

• Migration FAQ: A dedicated “2022 to 2026 FAQ” detailing frequently-asked questions is available here.

• In depth Legacy Spreadsheets Guide: A deep dive guide into every Legacy Spreadsheets endpoint and where to access that functionality in the new version of the API is available here.

• Developer Support: Workiva Developer Support teams are available to assist with specific integration challenges.

• Community Page: The Workiva Community Support Forums is a great place for all things API and Scripting.

Who should I contact if I have further questions?

Please contact your dedicated Workiva Account Manager or reach out to us via the Workiva Developer Support Community Page.