---
title: Dashboards API
description: List and retrieve Dashboards and their publish history via the ControlCom Connect REST API.
source: https://documentation.controlcomtech.com/api-reference/dashboards
---

# Dashboards

The Dashboards API reads the Dashboards in an organization: their metadata, their widget configuration, and their publish history.

> **Workflow Stage: Integrate**

## List Dashboards

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/dashboards
```

Requires the `ReadDashboards` permission. API key requests list the organization's public Dashboards; boards with **Public** switched off belong to their owner and are visible to signed-in users only.

* `search` (string): Case-insensitive filter on the Dashboard name.
* `archivedScope` (string): `active` (default), `archived` or `all`.
* `skip` (integer): Records to skip. See [Pagination](https://documentation.controlcomtech.com/api-reference#pagination).
* `take` (integer): Records to return per page.

**cURL**

```bash
curl 'https://api.controlcomtech.com/primary/v1/<organizationId>/dashboards?take=25' \
--header 'Authorization: Basic <Base64 encoded key ID and secret>'
```

**Response**

```json
{
  "count": 8,
  "items": [
    {
      "id": "clxd5...",
      "name": "Building Operations",
      "isPublic": true,
      "refreshIntervalSeconds": 600,
      "updatedDateTime": "2026-02-02T10:15:30.000Z"
    }
  ]
}
```

## Retrieve a Dashboard

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/dashboards/<dashboardId>
```

Requires the `ReadDashboards` permission. Returns the Dashboard including its `configuration`, the JSON document describing the board's widgets and layout.

## Publish History

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/dashboards/<dashboardId>/histories
```

Requires the `ReadDashboards` permission. Returns the board's published versions, each with the comment entered at publish time. This is the same history the editor's **History** panel restores from.

## Writing to Dashboards

Creating, updating, duplicating, archiving and restoring Dashboards are editor operations that record which user made the change, so they require a signed-in user's Bearer token; API keys are read-only for this resource. Build and publish boards in the ControlCom Connect [dashboard editor](https://documentation.controlcomtech.com/platform/dashboards/creating).