Dear Canva Developer Platform Team,
I'm writing to report a **critical breaking change** in the `@canva/asset` upload API that has been affecting many existing apps since approximately **January 13-14, 2026**.
---
## š“ Issue Summary
The `aiDisclosure` parameter in the `upload()` function appears to have become **mandatory** without prior deprecation notice. This change has caused widespread failures for users attempting to:
- Add assets to designs
- Upload to media library
**Affected API:**
```typescript
import { upload } from "@canva/asset";
await upload({
type: "image",
url: "https://example.com/image.jpg",
mimeType: "image/jpeg",
thumbnailUrl: "https://example.com/thumb.jpg",
aiDisclosure: "none" // ā Previously optional, now required
});
Request
To maintain backward compatibility and minimize disruption to the Canva app ecosystem, we kindly request:
Default fallback behavior: If
aiDisclosure
is missing or invalid, default to
"none"
(matching previous behavior)
Graceful deprecation: Instead of hard failures, show a console warning to guide developers:
ā ļø Warning: 'aiDisclosure' will be required in a future version. Please update your integration. Defaulting to 'none'. See: https://www.canva.dev/docs/apps/asset-upload
Advance notice: Provide a reasonable migration window (e.g., 30-60 days) before enforcing mandatory parameters
Why This Matters
Many production apps are now broken without any code changes on our end
Users are experiencing failures with no clear error messaging
This undermines trust in the stability of the Canva platform APIs
Our Commitment
We fully understand and support the importance of AI disclosure for transparency. We are committed to updating our integration to comply with this requirement. We simply ask for a graceful transition period to:
Protect existing users from unexpected failures
Give developers adequate time to update their code
Hi @liu thanks for raising your concern. At Canva we greatly emphasise backwards compatibility for the benefit of developers and users so that Apps can have long lives with minimal maintenance and users can have certainty in their experiences of the platform.
The aiDisclosure field was added as a new required field part of the V2 release of the Canva Apps SDK in September 2024. Developers have had over 15 months to upgrade. It was a major release, though not a breaking change to existing apps.
Could you explain what behaviour you are seeing? Is it just the types that are failing or a runtime error? If itās a error while using the app, it appears that youāve uncovered a bug where the field is expected even for apps on v1 of the Apps SDK.
We needed to make the field required rather than default to ānoneā to ensure no content is incorrectly undisclosed AI due to omission.
Actually, I upgraded to V2 quite early - in fact, my first version was already built on V2. However, the issue is about the enforcement timeline, not the field introduction itself.
What I observed:
Previously (until 2 days ago): passing aiDisclosure: 'ai' worked fine, and omitting it also worked
Since 2 days ago: suddenly it became strictly enforced, causing runtime errors
This affected both my production app and other apps Iāve seen
My concern:
While I understand the 15-month notice period for the fieldās introduction, the strict enforcement appears to have been enabled very recently without a clear transition period or warning. This is different from just adding a new field.
Impact:
My production app is now broken
Iāve noticed other developersā apps experiencing similar issues
Users are affected immediately
Suggestion:
I recommend implementing a proper transition strategy, such as:
A grace period with warnings before strict enforcement
Clear communication about enforcement timeline (not just field availability)
Perhaps defaulting to ānoneā temporarily with deprecation warnings
Could you confirm when the strict enforcement was enabled? This would help us understand the actual timeline we had to adapt.
In addition to our docs which mentioned the field, the typescript types are also a mechanism of ensuring that you are aware of the correct usage of our API. We apologise that we didnāt also have runtime validation for V2 earlier.
Our plan is to revert the runtime validation for the time being but I recommend disclosing as soon as possible, itās been 15 months since we announced it. Let me know if you have any trouble!
Thanks again for your report and swift responses, this aided us in getting to the bottom of the problem.
Thank you so much for the quick response and action! Really appreciate your teamās swift investigation and decision to revert the runtime validation temporarily.
I will immediately work with my team to update our code properly and add the aiDisclosure field to all relevant places. Weāll also remove those as any shortcuts and follow TypeScript types more strictly - lesson learned!
A suggestion for future rollouts:
I noticed many other apps seem to have the same issue. For similar breaking changes in the future, perhaps consider a progressive enforcement approach:
Phase 1: Warning logs (developers get alerted but apps still work)
Phase 2: Grace period with countdown notifications
Phase 3: Full enforcement
This would give developers time to react while maintaining platform stability.
Thanks again for your understanding and for working with the developer community. Your responsiveness really helps us maintain quality apps for Canva users.
Thanks for the thoughtful suggestions. Rest assured what you experienced was not intentional, our process will not cause working behaviour to become errors with no warning when all goes well, this was unintentional.
Glad to hear youāll be adding the field. Great idea to switch to using TypeScript more fully, it will make things easier in the long run for you Iām sure!
Thank you and your team for your prompt response and action! We greatly appreciate your quick investigation and decision to temporarily reinstate runtime validation.
I will immediately work with my team to update the code correctly and add the aiDisclosure field in all relevant locations. We will also stop using any shortcuts and more strictly adhere to TypeScript type definitionsāa great lesson learned!
I have already corrected and submitted the updated version for review.
However, I have a clarification question: Will incorrect values (like aiDisclosure: āaiā) be handled as part of this merge plan? I have several applications currently passing aiDisclosure: āaiā instead of the correct enum values.
I have already corrected and submitted the updated version for review.
To help our team quickly review the correct app, could you please supply your app ID? We will look to expedite the fix. Thanks in advance.
However, I have a clarification question: Will incorrect values (like aiDisclosure: āaiā) be handled as part of this merge plan? I have several applications currently passing aiDisclosure: āaiā instead of the correct enum values.
As a once off, we plan to disable runtime validation for released app versions for a short period time including allowing incorrect values as a grace period. However new app versions should use the correct values (either none or app_generated) and may throw errors otherwise.
Hi Liu, confirming as of today the temporary fix Gordon mentioned (for apps not using typescript or passing incorrect values) is out.
All apps should be working again, regardless of whether the new versions have been launched. Glad to hear youāve managed to submit the fixes as well!
Request
Why This Matters
Our Commitment
