diff --git a/plugins/gradle/java/src/service/project/wizard/GradleProjectImportBuilder.java b/plugins/gradle/java/src/service/project/wizard/GradleProjectImportBuilder.java
index 195550400a42..956d79a41e0b 100644
--- a/plugins/gradle/java/src/service/project/wizard/GradleProjectImportBuilder.java
+++ b/plugins/gradle/java/src/service/project/wizard/GradleProjectImportBuilder.java
@@ -5,6 +5,7 @@ import com.intellij.externalSystem.JavaProjectData;
 import com.intellij.ide.util.projectWizard.WizardContext;
 import com.intellij.openapi.application.ApplicationManager;
 import com.intellij.openapi.components.ServiceManager;
+import com.intellij.openapi.diagnostic.Logger;
 import com.intellij.openapi.externalSystem.model.DataNode;
 import com.intellij.openapi.externalSystem.model.ExternalSystemDataKeys;
 import com.intellij.openapi.externalSystem.model.internal.InternalExternalProjectInfo;
@@ -50,6 +51,8 @@ import java.util.stream.Collectors;
  */
 @Deprecated
 public final class GradleProjectImportBuilder extends AbstractExternalProjectImportBuilder<ImportFromGradleControl> {
+  private static final Logger LOG = Logger.getInstance(GradleProjectImportBuilder.class);
+
   public GradleProjectImportBuilder() {
     this(ProjectDataManager.getInstance());
   }
@@ -64,6 +67,14 @@ public final class GradleProjectImportBuilder extends AbstractExternalProjectImp
 
   public GradleProjectImportBuilder(@NotNull ProjectDataManager dataManager) {
     super(dataManager, () -> new ImportFromGradleControl(), GradleConstants.SYSTEM_ID);
+    LOG.warn("Do not use `GradleProjectImportBuilder` directly. Use instead:\n" +
+             "Internal stable Api\n" +
+             " Use `com.intellij.ide.actions.ImportModuleAction.doImport` to import (attach) a new project.\n" +
+             " Use `com.intellij.ide.impl.ProjectUtil.openOrImport` to open (import) a new project.\n" +
+             "Internal experimental Api\n" +
+             " Use `org.jetbrains.plugins.gradle.service.project.open.openProject` to open (import) a new gradle project.\n" +
+             " Use `org.jetbrains.plugins.gradle.service.project.open.importProject` to attach a gradle project to an opened idea project.",
+             new Throwable());
   }
 
   @NotNull
diff --git a/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportBuilder.kt b/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportBuilder.kt
index d5d0e39e5412..f7298febb081 100644
--- a/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportBuilder.kt
+++ b/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportBuilder.kt
@@ -22,6 +22,17 @@ import org.jetbrains.plugins.gradle.util.GradleConstants
 import javax.swing.Icon
 
 
+/**
+ * Do not use this project import builder directly.
+ *
+ * Internal stable Api
+ * Use [com.intellij.ide.actions.ImportModuleAction.doImport] to import (attach) a new project.
+ * Use [com.intellij.ide.impl.ProjectUtil.openOrImport] to open (import) a new project.
+ *
+ * Internal experimental Api
+ * Use [org.jetbrains.plugins.gradle.service.project.open.openProject] to open (import) a new gradle project.
+ * Use [org.jetbrains.plugins.gradle.service.project.open.importProject] to attach a gradle project to an opened idea project.
+ */
 class JavaGradleProjectImportBuilder : ProjectImportBuilder<Any>(), DeprecatedProjectBuilderForImport {
 
   override fun getName(): String = GradleBundle.message("gradle.name")
diff --git a/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportProvider.kt b/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportProvider.kt
index 621343dc9152..bcaf8a36f869 100644
--- a/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportProvider.kt
+++ b/plugins/gradle/java/src/service/project/wizard/JavaGradleProjectImportProvider.kt
@@ -9,6 +9,10 @@ import org.jetbrains.plugins.gradle.service.project.open.canImportProjectFrom
 import org.jetbrains.plugins.gradle.util.GradleConstants
 import org.jetbrains.plugins.gradle.util.GradleConstants.SYSTEM_ID
 
+/**
+ * Do not use this import provider directly.
+ * @see JavaGradleProjectImportBuilder
+ */
 class JavaGradleProjectImportProvider : AbstractExternalProjectImportProvider(JavaGradleProjectImportBuilder(), SYSTEM_ID) {
 
   override fun createSteps(context: WizardContext): Array<ModuleWizardStep> {
diff --git a/plugins/gradle/src/org/jetbrains/plugins/gradle/service/project/open/GradleProjectImportUtil.kt b/plugins/gradle/src/org/jetbrains/plugins/gradle/service/project/open/GradleProjectImportUtil.kt
index cb1cc88add0b..0b321d2fe2a5 100644
--- a/plugins/gradle/src/org/jetbrains/plugins/gradle/service/project/open/GradleProjectImportUtil.kt
+++ b/plugins/gradle/src/org/jetbrains/plugins/gradle/service/project/open/GradleProjectImportUtil.kt
@@ -29,6 +29,7 @@ import com.intellij.util.EnvironmentUtil
 import com.intellij.util.io.exists
 import com.intellij.util.text.nullize
 import org.gradle.util.GradleVersion
+import org.jetbrains.annotations.ApiStatus
 import org.jetbrains.plugins.gradle.service.GradleInstallationManager
 import org.jetbrains.plugins.gradle.settings.DistributionType
 import org.jetbrains.plugins.gradle.settings.DistributionType.DEFAULT_WRAPPED
@@ -52,6 +53,7 @@ fun canImportProjectFrom(file: VirtualFile): Boolean {
   return file.children.any(::isGradleProjectFile)
 }
 
+@ApiStatus.Experimental
 fun openProject(projectFile: VirtualFile, projectToClose: Project?, forceOpenInNewFrame: Boolean): Project? {
   if (!canImportProjectFrom(projectFile)) return null
   val projectDirectory = findExternalProjectDirectory(projectFile)
@@ -66,6 +68,7 @@ fun openProject(projectFile: VirtualFile, projectToClose: Project?, forceOpenInN
   return project
 }
 
+@ApiStatus.Experimental
 fun importProject(projectDirectory: String, project: Project) {
   LOG.info("Import project at $projectDirectory")
   val projectSdk = ProjectRootManager.getInstance(project).projectSdk