Update Cloud docs with more details regarding Cloud vs self hosted (#2818) (#2826)

pwizla · meganelacheny · web-flow · commit e33b3d050360 · 2025-11-19T14:36:10.000+01:00
Co-authored-by: meganelacheny &lt;megane.lacheny@strapi.io&gt;
diff --git a/docusaurus/docs/cloud/getting-started/cloud-fundamentals.md b/docusaurus/docs/cloud/getting-started/cloud-fundamentals.md
@@ -19,3 +19,7 @@ Before going any further into this Strapi Cloud documentation, we recommend you
 - **Types of Strapi Cloud users** <br/> There can be 2 types of users on a Strapi Cloud project: owners and maintainers. The owner is the one who has created the project and has therefore access to all features and options for the project. Maintainers are users who have been invited to contribute to an already created project by its owner. Maintainers, as documented in the [Collaboration](/cloud/projects/collaboration) page, cannot view and access all features and options from the Strapi Cloud dashboard.
 
 - **Support** <br/> The level of support provided by the Strapi Support team depends on the Strapi Cloud plan you subscribed for. The Free plan does not include access to support. The Essential and Pro plans include Basic support while the Scale plan includes Standard support. Please refer to the [dedicated support article](https://support.strapi.io/support/solutions/articles/67000680833-what-is-supported-by-the-strapi-team#Not-Supported) for all details regarding support levels.
+
+- **API access in Strapi Cloud vs self-hosted** <br/> The REST and GraphQL APIs behave the same on Strapi Cloud and on self-hosted servers. The only differences are the URLs:
+    - Base API domain: On Strapi Cloud, your API uses the domain of the environment (e.g. `https://<project>.strapiapp.com/api/...`), or your custom domain if you set one (see [Domains documentation](/cloud/projects/settings#domains)). A self-hosted project would use whatever domain you expose.
+    - Media Library URLs: Media fields in REST and GraphQL responses from Strapi Cloud always use the project media domain (e.g. `<project>.media.strapiapp.com`), even when you access the API through a custom domain. Self-hosted projects return URLs from the configured upload provider, so the domain can match your own site or CDN. When you move a project from self-hosted to Strapi Cloud, make sure your frontend reads the absolute URLs returned by the API or accepts the Strapi Cloud media domain.
diff --git a/docusaurus/docs/cloud/projects/settings.md b/docusaurus/docs/cloud/projects/settings.md
@@ -457,6 +457,10 @@ All existing domains for your Strapi Cloud project are listed in the <Icon name=
 
 Default domain names are made of 2 randomly generated words followed by a hash. They can be replaced by any custom domain of your choice.
 
+:::note
+Custom domains are not available on the Free plan. Downgrading to the Free plan will result in the application domain's being restored to the default one.
+:::
+
 1. Click the **Connect new domain** button.
 2. In the window that opens, fill in the following fields:
 
@@ -473,14 +477,12 @@ Default domain names are made of 2 randomly generated words followed by a hash.
 To finish setting up your custom domain, in the settings of your domain registar or hosting platform, please add the Target value (e.g., `proud-unicorn-123456af.strapiapp.com`) as a CNAME alias to the DNS records of your domain.
 :::
 
-:::caution Custom domains and assets
+:::info Custom domains and assets
 When using custom domains, these domains do not apply to the URLs of uploaded assets. Uploaded assets keep the Strapi Cloud project-based URL.
 
 This means that, if your custom domain is hosted at `https://my-custom-domain.com` and your Strapi Cloud project name is `my-strapi-cloud-instance`, API calls will still return URLs such as `https://my-strapi-cloud-instance.media.strapiapp.com/example.png`.
-:::
 
-:::note
-Custom domains are not available on the Free plan. Downgrading to the Free plan will result in the application domain's being restored to the default one.
+Media library queries over REST or GraphQL always return the project media domain on Strapi Cloud. If you move from a self-hosted project, where media URLs can match your own domain or CDN, plan to keep using the absolute URLs from the API or adjust your frontend to allow the Strapi Cloud media domain (see [Cloud Fundamentals](/cloud/cloud-fundamentals) for more details).
 :::
 
 ### Variables
diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt
@@ -1279,10 +1279,12 @@ Default domain names are made of 2 randomly generated words followed by a hash.
 To finish setting up your custom domain, in the settings of your domain registar or hosting platform, please add the Target value (e.g., `proud-unicorn-123456af.strapiapp.com`) as a CNAME alias to the DNS records of your domain.
 :::
 
-:::caution Custom domains and assets
+:::info Custom domains and assets
 When using custom domains, these domains do not apply to the URLs of uploaded assets. Uploaded assets keep the Strapi Cloud project-based URL.
 
 This means that, if your custom domain is hosted at `https://my-custom-domain.com` and your Strapi Cloud project name is `my-strapi-cloud-instance`, API calls will still return URLs such as `https://my-strapi-cloud-instance.media.strapiapp.com/example.png`.
+
+Media library queries over REST or GraphQL always return the project media domain on Strapi Cloud. If you move from a self-hosted project, where media URLs can match your own domain or CDN, plan to keep using the absolute URLs from the API or adjust your frontend to allow the Strapi Cloud media domain (see [API access in Strapi Cloud](/cloud/cloud-fundamentals#api-access-in-strapi-cloud-vs-self-hosted) for more details).
 :::
 
 :::note
