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 and 2024.7.2.
- 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.
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."}]}