# Dashboard APIs The Veza Dashboard API (referred to as "Assessment Reports" in the API) enables programmatic access to Veza dashboards, queries, and analytics. You can use these APIs to automate dashboard management, retrieve time-series data, and integrate Veza insights into your own tools and workflows. {% hint style="info" %} These customer-facing APIs are available under the prefix `/api/preview/assessments/`, for example: `https://company.veza.com/api/preview/assessments/reports` {% endhint %} The Dashboard API enables you to: * List and filter dashboards by integration, category, or risk level * Retrieve time-series and comparison data for trend analysis * Create custom dashboards programmatically * Share dashboards with teams via API * Track dashboard changes and query results over time ## Important concepts ### Terminology * **Assessment Reports** (API term) = **Dashboards** (UI term) * **Assessment Queries** (API term) = **Saved Queries** (UI term) Conceptually, these APIs manage [Reports](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/reports.md), presented to users in Veza as Dashboards for visibility, action, and collaboration. A Report is a collection of [Saved Queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md), which can be constructed using the [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md) or [Query Builder API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder.md). ### Understanding dashboard identifiers Dashboard IDs are stable UUID identifiers that remain constant regardless of dashboard name changes, modifications to dashboard contents, or sharing status. IDs are universally unique identifiers such as `64e4231c-ead9-4bf0-bed7-afa94511f476`. You can find dashboard IDs by: 1. Using the List Dashboards endpoint with filters 2. Viewing the dashboard URL in the Veza UI: `/app/dashboard/library/{dashboard_id}` 3. Checking the [OOTB Dashboards reference](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/ootb-dashboards.md) for system dashboard IDs ### Dashboard types {% hint style="warning" %} Attempting to modify or delete system-created dashboards will return a `422 Unprocessable Entity` error. {% endhint %} Dashboards have a `type` field indicating their origin: * **`system_created`**: Out-of-the-box (OOTB) dashboards created and managed by Veza. These cannot be modified or deleted via API and are available to all tenants automatically. * **`user_created`**: Custom dashboards created using the Veza GUI or APIs, specific to your organization. These dashboards can be modified, shared, and deleted via API. ## Authentication You can issue new API keys from **Administration** > **API Keys** > [*Add New API Key*](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md). Provide the key as the bearer auth token in the header of each request. Required Roles: | Operation | Required Roles | | ------------------------ | ----------------------------- | | View dashboards | `viewer`, `operator`, `admin` | | Create/modify dashboards | `admin`, `operator` | | Share dashboards | `admin` | Example: ```bash curl --location --request GET \ 'https://company.veza.com/api/preview/assessments/reports' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' ``` ## API Endpoints ### Dashboard Management #### List All Dashboards {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Get Specific Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{id}" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Create Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Update Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{id}" method="put" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Delete Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{id}" method="delete" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} *** ### Dashboard Analytics #### Get Time-Series Data {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{id}/queries/timeseries" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Get Comparison Data {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{id}/queries/comparison" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} *** ### Sharing Operations #### Share Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{report\_id}:share" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} #### Unshare Dashboard {% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/preview/assessments/reports/{report\_id}:unshare" method="post" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media) {% endopenapi %} *** ## Related Documentation * [API Examples](/4yItIzMvkpAvMVFAamTf/developers/api/dashboards/examples.md) - Ready-to-use code examples for common operations * [OOTB Dashboards](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/ootb-dashboards.md) - Complete list of out-of-the-box dashboards with IDs * [Dashboards Overview](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards.md) - Dashboard features and UI capabilities * [Saved Queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md) - Working with dashboard queries * [Dashboard Sharing](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/dashboard-sharing.md) - Sharing workflows and requirements * [API Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) - How to create and use API keys * [Query Builder APIs](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder.md) - Working with saved queries via API --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/dashboards.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.