API Previews at Workiva#
API Previews let customers try pre-release Workiva Platform API capabilities before they are generally available (GA). They help Workiva gather feedback on new APIs and significant enhancements so we can improve behavior, documentation, and reliability before a wider release.
API Previews are not a substitute for our versioning policy. How GA APIs are versioned, deprecated, and classified as breaking or additive is described in API versioning. This page describes previews only.
Terminology#
Preview Features refers to the program under which preview participation is offered, including the Preview Features Agreement you accept to take part.
API Preview is how a specific preview appears on the Workiva developer site, usually as a listed capability you can learn about. A given listing typically corresponds to one Preview Features period with a defined start and end.
Preview Feature Agreement and eligibility#
To participate in an API Preview, you must accept Workiva’s Preview Feature Agreement. For information on the Preview Feature agreement reach out to your CSM or Partner Success Manager.
To call preview APIs, you will need a valid and active API Grant, just as you would for any other Workiva API usage. For detailed information about obtaining and managing API Grants, refer to the API Details and Setup sections of the Workiva API documentation. Each preview may also include specific access instructions in its onboarding materials on the developer site.
What to expect during a preview#
API Preview capabilities are pre-release. They may change, behave differently from GA APIs, and are not covered by the same stability commitments as GA. These previews are meant for gathering feedback on pre-release APIs. They should not be relied upon for business critical needs.
For each preview, Workiva aims to give you clear information about:
When the preview goes live, when you can start using it
How long it is expected to run
When it is scheduled to end
If those dates change, updated timing and context when helpful
Near the scheduled end, you should receive reminders about when the preview ends and what happens next.
When an API Preview ends#
When a Preview Features period ends, Workiva removes the preview from the developer site, including preview documentation listings where applicable. Preview API access may no longer be available or supported.
Workiva will communicate that the preview has ended, that preview documentation has been removed where applicable, and what that means for continued API use, your API Grants, and your integrations, including whether and how the capability becomes available under GA and API versioning, or whether Workiva is not proceeding to GA for that experiment.
You should receive a clear summary of the outcome after the preview ends, for example path to GA, further work, or discontinuation, including timing or next steps when they apply.
Preview length#
Each API Preview has a start date and end date. The active period is typically no more than ninety (90) days, but some previews might lend themselves to longer term engagements.
Finding API Previews#
View active and upcoming API Previews on the Workiva developer site. Each listing includes documentation and how to request access.
The preview listing page shows go-live timing, how long each preview runs, and when it is scheduled to end.
Relationship to general availability and API versioning#
While a capability is in preview, SLA, documentation, and eligibility may differ from GA. After a capability becomes generally available, it is subject to API versioning:
Breaking changes are delivered only in new date-based major API versions, following the cadence and rules described there.
Additive, non-breaking changes may ship to supported versions as described there and are reflected in the Changelog for that version.
Deprecation and sunset for released API versions follow that policy. Preview participation does not change GA lifecycle rules once a version is generally available.
For GA endpoints, continue to send the X-Version header and follow the guidance in API versioning.
Previews and Chains#
Preview APIs are not offered as built-in Chains nodes or commands. Only GA endpoints that the Chains product includes appear as first-class Chain nodes. During a preview, integrations typically use the API directly, for example HTTP or custom automation, until GA Chains support exists.
FAQ#
Q: Is an API Preview the same as a generally available API?
A: No. Previews are time-limited and offered under the Preview Features Agreement for early feedback. Generally available APIs follow API versioning for versioning, support expectations, and how changes are released.
Q: What is the difference between API Preview and Preview Features?
A: API Preview usually refers to what you see on the developer site, a specific preview you can read about and join. Preview Features is the program, including the agreement, under which that preview runs. Both refer to the same type of pre-release API participation.
Q: How do I get access to a preview?
A: Use the instructions on the developer site, typically through your CSM, or coordinate with the Workiva product team if you already work with them. You need the Preview Features Agreement accepted and any required steps such as an API Grant, as described for that preview.
Q: How long will a preview last?
A: Each preview has communicated start and end dates. The active period is usually up to ninety (90) days unless Workiva states otherwise for that preview.
Q: Can the API change during a preview?
A: Yes. Previews are pre-release; behavior, shape, and documentation may change. Workiva should communicate material changes according to the preview’s onboarding and update practices. For GA APIs, breaking vs additive changes follow API versioning.
Q: Will preview APIs appear as Chains nodes?
A: No. Preview APIs are not shipped as Chains nodes. GA endpoints may become Chains nodes when Workiva adds them to the Chains product.
Q: What happens when the preview ends?
A: Preview documentation is removed from the developer site and preview API access typically ends or is unsupported. Workiva will tell you the preview has ended, what was removed, and what it means for your integrations and GA plans, including if the capability will not go to GA.
Q: Can breaking changes from a preview be applied to an existing GA API version?
A: No. Breaking changes ship only in new date-based major versions, as defined in API versioning. A preview may try different shapes before GA; what is released as GA must follow that policy.
Q: Where can I read about API versioning?
A: See API versioning on the Workiva developer site.
Q: How do I call preview APIs?
A: Each API Preview has its own X-Version header that includes the Preview Features identifier appended to the API version. For example, if an API preview is for version 2026-01-01 with a preview period identifier, the header would be X-Version: 2026-01-01.preview.identifier. Refer to the specific preview’s documentation on the Workiva developer site for the exact X-Version header value to use for that preview.