1 files changed, 61 insertions, 0 deletions
diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md
new file mode 100644
index 00000000000..dd9144d1319
--- /dev/null
+++ b/doc/api/metrics_user_starred_dashboards.md
@@ -0,0 +1,61 @@
+# User-starred metrics dashboards API
+
+The starred dashboard feature makes navigating to frequently-used dashboards easier
+by displaying favorited dashboards at the top of the select list.
+
+## Add a star to a dashboard
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31316) in GitLab 13.0.
+
+```plaintext
+POST /projects/:id/metrics/user_starred_dashboards
+```
+
+Parameters:
+
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `dashboard_path` | string        | yes      | URL-encoded path to file defining the dashboard which should be marked as favorite.   |
+
+```shell
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \
+ --data-urlencode "dashboard_path=config/prometheus/dashboards/common_metrics.yml"
+```
+
+Example Response:
+
+```json
+{
+  "id": 5,
+  "dashboard_path": "config/prometheus/common_metrics.yml",
+  "user_id": 1,
+  "project_id": 20
+}
+```
+
+## Remove a star from a dashboard
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31892) in GitLab 13.0.
+
+```plaintext
+DELETE /projects/:id/metrics/user_starred_dashboards
+```
+
+Parameters:
+
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `dashboard_path` | string        | no      | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied all dashboards within given projects will be removed from favorites.   |
+
+```shell
+curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \
+ --data-urlencode "dashboard_path=config/prometheus/dashboards/common_metrics.yml"
+```
+
+Example Response:
+
+```json
+{
+  "deleted_rows": 1
+}
+```