--- title: "Mini guides" slug: "api-mini-guide" updated: 2026-01-03T13:44:30Z published: 2026-01-03T13:44:30Z canonical: "docs.preset.io/api-mini-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.preset.io/llms.txt > Use this file to discover all available pages before exploring further. # API Mini Guide This mini guides collection focuses on common Preset API use cases. Before you start, make sure to generate your Preset API key for authentication. You can find detailed API key management and relevant endpoint information in the [Preset API documentation](https://api-docs.preset.io/). --- ## Take a Fresh Chart Screenshot ### Scenario You want to programatically get a screenshot of a Chart as up-to-date as possible - i.e., not from cache. ### Steps 1. Make a POST call to the Preset [Refresh Chart](https://api-docs.preset.io/#dae775c3-dbb7-4966-a553-daac3ef76abd) endpoint. **Note:** This might take up to a few minutes, so please wait at least 5 minutes before going to the next step. 2. After the chart is refreshed, make a GET call to the [Get Chart Screenshot](https://api-docs.preset.io/#00765aca-a0c9-410f-8b5c-74eafac325f5) endpoint. 3. This will return a screenshot of the most up to date chart. --- ## Delete unused assets from the Workspace ### Scenario You want to maintain Workspace content, by deleting assets that aren't in use. ### Steps #### Get empty dashboards First get a list of all dashboards IDs for your workspace with the[Get All Dashboards from Workspace](https://api-docs.preset.io/#2787cb4e-39e9-4b99-92e0-86282bc5794a) endpoint. You can find them in the response, in the field `ids`. Note that this endpoint has a limit of 100 results per request, so if you have more than 100 dashboards, you need to navigate through the pagination (by changing the `page` value in the endpoint). Then iterate through each ID and call the [Get Dashboard](https://api-docs.preset.io/#f5e5c6d2-5f38-40bd-8c6f-9cf581eb799a) endpoint. The response contains a `chart` field that displays a list of all charts belonging to this dashboard. You can isolate the empty dashboards by selecting those that have an empty list for that field. Keep in mind that if you have dashboards with only **text** (for example a homepage dashboard with links to other dashboards), this isn't considered a chart, so you can be extra carefull and look for other fileds before making a decision on deleting the asset or not: - Check if `published` is set to `false` to validate if the dashboard is a **draft**. - Check if there are any elements in the `position_json` (**text** elements are declared as `MARKDOWN-{{id}}`). #### Find orphan charts (that aren't added to any dashboard) First get a list of all charts IDs with the [Get Charts](https://api-docs.preset.io/#8160eb8e-d278-447a-9edc-7f0b3491052d) endpoint. You can find them in the response, in the field `ids`. Note that this endpoint has a limit of 100 results per request, so if you have more than 100 charts, you need to navigate through the pagination (by changing the `page` value in the endpoint). Then for each ID make a call to the [Get Chart](https://api-docs.preset.io/#7c1a023a-0947-40b7-8ef5-4a1b4a15a85f) endpoint. The response contains a `dashboards` field, which is a list of all dashboards the chart is associated with. You can isolate orphan charts by selecting those that have an empty list for this field. If you have use-cases in which charts aren't getting added to dashboards, you can perform additional validations to the payload, such as: - Check if the chart is certified by checking the `certification_details` and `certified_by` values. #### Delete Assets Once you have a list of charts and/or dashboards you would like to delete, you can iterate through the list of their IDs and make calls to the delete endpoints: - [For dashboards](https://api-docs.preset.io/#e9d22b2a-a0fc-4fd8-a537-fadee79a77e6) - [For charts](https://api-docs.preset.io/#74cc2237-901f-474e-92f3-68b9a2db51bb) --- ## Control dashboard filter values with the URL (custom permalink generation) ### Scenario You have a dashboard with filters, and you want to share a link with a particular filter selection applied. ### Steps #### Through the UI To generate the link from the UI, apply the desired filter selection, and then generate a permalink. #### Through the API It's possible to dynamically generate permalinks through the API, using the [Create a Permalink to a Dashboard](https://api-docs.preset.io/#64b92df5-16b5-47a4-b02a-2af7e24071f0) endpoint. To do so: 1. This endpoint requires a payload to specify the filter configuration, so first let's retrieve the current filter configuration for the desired dashboard, using the [Get a Dashboard](https://api-docs.preset.io/#f5e5c6d2-5f38-40bd-8c6f-9cf581eb799a) endpoint. You can find the dashboard ID directly in its URL (`https://{WorkspaceSlug}.{WorkspaceRegion}.app.preset.io/superset/{{dashboardID}}`). 2. The response includes a `json_metadata` value, which is a `string` that can be loaded as a JSON. 3. Get the value for the `native_filter_configuration` key, from the `json_metadata` JSON. 4. The `native_filter_configuration` key includes the configuration for all filters. We're specifically looking for: 1. The `id`. 2. The `defaultDataMask` configuration. 5. Use this information to create a payload with this structure: ``` { "dataMask": { "{{FilterID}}": { "id": "{{FilterID}}", "extraFormData": { "filters": [ { "col": "{{Column}}", "op": "{{Operator}}", "val": ["{{Value}}"] }] }, "filterState": { "validateStatus": false, "label": "{{Value}}", "value": ["{{Value}}"] }, "ownState": {}, "__cache": { "validateStatus": false, "label": "{{Value}}", "value": ["{{Value}}"] } } }, "urlParams": [] } ``` 1. Use this payload in the [Create a Permalink to a Dashboard](https://api-docs.preset.io/#64b92df5-16b5-47a4-b02a-2af7e24071f0) endpoint. --- ## Retrieve a Chart's status ### Scenario You want to check the chart's status to find any with a broken state. ### Steps 1. **Run the [Refresh a Chart](https://api-docs.preset.io/#dae775c3-dbb7-4966-a553-daac3ef76abd) API call.** This will ensure that the chart has the latest data by refreshing the underlying metadata. 2. **Run the [Get Chart's Data](https://api-docs.preset.io/#bcd4faf6-4107-45f3-9667-84f74c139f43) API call.** Retrieving the output and validating for potential errors.