[TEST] [Bug]:

[pwizla]

Link to the documentation page or resource

https://docs.strapi.io/dev-docs/plugins/upload/

Describe the bug

The documentation "Using plugins - Upload" chapter "Upload entry files" section "The corresponding code is be:" in Strapi v5 does not correspond to actual practice and vice versa.

In the image/example provided by Strapi in the "refId" section, the value refers to "documentId", but in reality the value is "id" not "documentId". I think this will confuse many people, please fix it ASAP.
Image

Video:
https://drive.google.com/file/d/1PbCsfHv011DCFll3ehG5KiQx6xi0nkAy/view?usp=sharing

Additional context

No response

Suggested improvements or fixes

No response

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Hi there! 👋

Thank you so much for taking the time to report this issue and for providing such clear details, including screenshots and a video. Your effort to help improve the Strapi documentation is truly appreciated, and we understand how confusing it can be when the docs and actual behavior don’t match up.

About the refId Value in Strapi v5

You are correct that, starting with Strapi v5, the platform has transitioned from using id to documentId for identifying entries in most Content API calls, as part of the move to the new Document Service API. This change is reflected in the breaking changes documentation, which recommends using documentId instead of id for consistency and future compatibility.

However, when it comes to uploading files and linking them to entries using the Upload plugin, the official documentation for Strapi v5 still shows examples where refId is set to the entry’s id (not documentId). Here’s the relevant code snippet from the docs:

<form>
  <input type="file" name="files" />
  <input type="text" name="ref" value="api::restaurant.restaurant" />
  <input type="text" name="refId" value="5c126648c7415f0c0ef1bccd" />
  <input type="text" name="field" value="cover" />
  <input type="submit" value="Submit" />
</form>

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  await fetch('/api/upload', {
    method: 'post',
    body: new FormData(e.target)
  });
});

As you’ve noticed, in practice, the API expects the classic id value for refId, not the new documentId. This is a known point of confusion, especially since most other APIs in Strapi v5 have moved to documentId for entry identification.

What’s Happening?

• Upload Plugin Exception: The Upload plugin’s API still expects the legacy id for refId, not the new documentId. This is an exception to the general v5 migration pattern and is not yet fully aligned with the rest of the platform.
• Documentation Mismatch: The documentation could be clearer about this exception, and your feedback highlights a real need for improvement.

What You Can Do Right Now

• Continue using id for refId when uploading files and linking them to entries via the Upload plugin in Strapi v5.
• For all other Content API operations, follow the new pattern and use documentId as described in the migration guide.

Next Steps

• I’ll flag this for the documentation team so they can clarify this exception in the Upload plugin docs. If you’d like to track or contribute to this update, feel free to open a PR or follow the documentation repository.
• If you encounter any further issues or have suggestions, you’re always welcome to join our community forum or Discord for more support.

If you believe this is a product bug or needs a core fix, please let us know, and we can transfer this issue to the main Strapi repository and tag @pwizla for further review.

Thank you again for your attention to detail and for helping make Strapi better for everyone! 🚀

— The Strapi Team

---

References:

• Upload entry files (Strapi v5 docs)
• documentId vs id breaking change

📚 Relevant documentation:

• Release notes|5.1.0
• Core service methods use the Document Service API|Core service methods use the Document Service API
• Model config path uses uid instead of dot notation|Model config path uses uid instead of dot notation
• Release notes|Dev Docs
• Release notes|Dev Docs
• Release notes|Updated content
• Release notes|5.5.0
• Release notes|Release notes
• Entity Service deprecated|Entity Service deprecated
• Release notes|Chore, fixes, typos, and other improvements
• Community & Support|Community & Support
• Strapi v4 to Strapi 5 breaking changes|Content API
• Upload a file at entry creation is no longer supported|Upload a file at entry creation is no longer supported
• REST API: Upload files|Upload entry files
• documentId should be used instead of id in Content API calls|documentId should be used instead of id in Content API calls

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.