Public API v2 → Rename and Move Dashboards Endpoint

About the /dashboards endpoint

As a Super User or a user with the SuperRole security role, you can use the/dashboards endpoint to rename dashboards, move them to other locations, or transfer their ownership. This endpoint is available starting 2024.1.5.

Notes

You must transfer the ownership of dashboards that you do not own to be able to rename or move them via this endpoint.
You must move these dashboards to folders you have access to to have them listed in the Catalog.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

Use the HTTPS or HTTP scheme according to your installation. You must use the HTTPS scheme to run the API endpoints successfully on Cloud installations.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenantName}/dashboards

Examples:

https://mycluster.incorta.com/incorta/api/v2/default/dashboards
https://10.1.2.3:8080/incorta/api/v2/default/dashboards

Request URL Parameters

Parameter	Type	Description	Required
tenantName	String	The tenant name (case-sensitive)	Required

HTTP method

PATCH

Request headers

{  
"Content-Type": "application/json",  
"Accept": "application/json",  
"Authorization": "Bearer {access_token}"  
}

You must use a valid access token of the Super User or a tenant user with the SuperRole security role. For information about how to create an access token, refer to Public API v2 → Create an API access token.

Request body

{ "dashboardUpdateItems": [
    { "guid": "string",
      "parentId": number,
      "name": "string",
      "transferOwnership": boolean }
 ]}

Request body parameters

Parameter	Type	Description	Required
dashboardUpdateItems	Array of objects	A list of dashboards that you want to rename or move. Each dashboard is represented by a multi-property object.	Required
dashboardUpdateItem > guid	String	The GUID of the dashboard you want to rename or move	Required
parentId	Integer	The ID of the parent folder that you want to move the dashboard to. You must have Edit access rights to this folder.	Optional
dashboardUpdateItem > name	String	The new name of the dashboard (case-sensitive). The dashboard name should be unique in the folder.	Optional
dashboardUpdateItem > transferOwnership	Boolean	Specify if you want to transfer the ownership of the dashboard or not. You must set it to `TRUE` if you do not already own the dashboard to be able to rename or move it.	Optional

Example:

{ "dashboardUpdateItems": [
    { "guid": "7966c90a-0923-4me1-833d-6464ste2dc964",
      "parentId": 2012,
      "name": "NewName",
      "transferOwnership": yes },
   { "guid": "7688c91a-0993-bbs1-703d-ab66xc289jks77",
      "parentId": 2020,
      "name": "MyDashboard"}
 ]}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
207	Multi-Status	`{"responseList": [{"dashboardGuid": "string", "result": "string", "errorMessage": "string"}]}` For more details, see Response parameters.
400	Bad Request You provided invalid values.	`{"message": "string"}` Example: `{Unexpected character ('x' (code 120)) in numeric value: expected digit (0-9) to follow minus sign, for valid numeric value}`
401	Unauthorized The endpoint couldn’t run successfully due to authentication errors, such as an invalid or expired access token.	`{"message": "string"}` Example: `{"message": "INC_09030108: Invalid authentication header. Invalid Token [abcd1234]"`
403	Forbidden You do not have sufficient access rights to run the endpoint. Only a Super User or a user with SuperRole can run it.	`{"message": "string"}` Example: `{"message": "INC_02030000: Only the user(s) with super role can modify."}`
404	Not Found The tenant doesn't exist or is disabled.	`{"message": "string"}` Example: `{"message": "Invalid [DEFAULT] tenant in resource path"}`

Response parameters

The following are the parameters in the /dashboards endpoint response when the endpoint returns code 207.

{"responseList": [  
    {"dashboardGuid": "string",  
      "result": "string",  
      "errorMessage": "string" }  
  ]}

The following table describes these response parameters.

Parameter	Type	Description
responseList	Array of objects	The response per dashboard in the request
dashboardGuid	String	The GUID of the dashboard
result	String	The request result for the respective dashboard: FAILED or SUCCESS
errorMessage	String	The error message in the case of a failed request

Response example

{"responseList": [  
{"dashboardGuid": "4597c90a-0323-23ed-853d-6464fe2dcon4",  
         "result": "FAILED",  
         "errorMessage": "INC_02010000: You are not authorized to EDIT the  FOLDER of ID [2012]"},  
{"dashboardGuid": "7997c50a-0323-76e1-866d-6464fe2dc964",  
         "result": "SUCCESS"},  
{"dashboardGuid": "7997c90a-0323-49e1-853d-6464fe2323",  
         "result": "FAILED",  
         "errorMessage": "INC_05111201: The [7997b90a-0323-89e1-8bnd-6964fe2dc64] DASHBOARD cannot be found."}  
 ]}

Content