Dashboards API

Overview

The Dashboards API allows you to create, retrieve, update, delete, duplicate, and share dashboards programmatically.

Base path:

https://semaphor.cloud/api/management/v1/dashboards

All endpoints require authentication and permission checks.

Example: Create a Dashboard via API

1. Get a project token

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_07472e99-ad83-4cb1-89c1-9c0ae82fc9cc",
    "projectSecret": "10f5bf2b-a8b5-4403-ba1b-d8a2100f7391"
  }'

2. Create a dashboard

curl -X POST https://semaphor.cloud/api/management/v1/dashboards \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Dashboard via API",
    "description": "This is a test dashboard",
    "template": {
      "id": "123456",
      "title": "My Dashboard",
      "description": "Description: My Dashboard",
      "sheets": [
        {
          "id": "07b6af60-2a82-4eeb-a005-616af4fc751e",
          "title": "Sheet 1",
          "frames": [
            {
              "id": "74a0f4a3-f18b-4fe3-9e30-dbbfd2305485",
              "cards": [
                {
                  "id": "7369f283-3b52-4b6a-b507-e79c1d205000",
                  "title": "Title",
                  "description": "Description",
                  "preferences": {},
                  "type": "bar",
                  "sql": "",
                  "data": [],
                  "dataSource": {
                    "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
                    "connectionType": "API",
                    "mode": "database",
                    "selectedEntities": [
                      {
                        "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
                        "connectionType": "API",
                        "type": "table",
                        "database": "",
                        "schema": "",
                        "name": "api",
                        "dialect": "duckdb"
                      }
                    ],
                    "dbSelection": {
                      "database": "",
                      "schema": "",
                      "entityType": "table"
                    }
                  },
                  "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
                  "lastSelectedDatabase": "",
                  "lastSelectedSchema": "",
                  "datamodelId": "",
                  "lastSelectedTable": "api",
                  "config": {
                    "metricColumns": [
                      {
                        "id": "metrics-api-order_id-1753119318387",
                        "name": "order_id",
                        "dataType": "VARCHAR",
                        "label": "Count of Order Id",
                        "qualifiedEntityName": "api",
                        "entityId": "api",
                        "entityName": "api",
                        "entityType": "table",
                        "role": "metric",
                        "aggregate": "COUNT"
                      }
                    ],
                    "groupByColumns": [
                      {
                        "id": "groupBy-api-ship_mode-1753119320338",
                        "name": "ship_mode",
                        "dataType": "VARCHAR",
                        "label": "Ship Mode",
                        "qualifiedEntityName": "api",
                        "entityId": "api",
                        "entityName": "api",
                        "entityType": "table",
                        "role": "groupby"
                      }
                    ]
                  },
                  "lastSelectedDatamodelId": "",
                  "customCfg": null
                }
              ],
              "activeCardId": "7369f283-3b52-4b6a-b507-e79c1d205000"
            }
          ],
          "layouts": {
            "lg": [
              {
                "w": 18,
                "h": 36,
                "x": 0,
                "y": 0,
                "i": "74a0f4a3-f18b-4fe3-9e30-dbbfd2305485",
                "moved": false,
                "static": false
              }
            ]
          }
        }
      ]
    }
  }'

Expected Response:

{
  "id": "123456",
  "projectId": "p_07472e99-ad83-4cb1-89c1-9c0ae82fc9cc",
  "secret": "ds_68846bf8-bab6-4cac-9aa5-b486c1d37769",
  "title": "Test Dashboard via API",
  "template": "{\"id\":\"123456\",\"title\":\"Test Dashboard via API\",\"description\":\"This is a test dashboard\",\"sheets\":[{\"id\":\"07b6af60-2a82-4eeb-a005-616af4fc751e\",\"title\":\"Sheet 1\",\"frames\":[{\"id\":\"74a0f4a3-f18b-4fe3-9e30-dbbfd2305485\",\"cards\":[{\"id\":\"7369f283-3b52-4b6a-b507-e79c1d205000\",\"title\":\"Title\",\"description\":\"Description\",\"preferences\":{},\"type\":\"bar\",\"sql\":\"\",\"data\":[],\"dataSource\":{\"connectionId\":\"c_75e24958-4470-4b13-8fef-a2de1d9fab98\",\"connectionType\":\"API\",\"mode\":\"database\",\"selectedEntities\":[{\"connectionId\":\"c_75e24958-4470-4b13-8fef-a2de1d9fab98\",\"connectionType\":\"API\",\"type\":\"table\",\"database\":\"\",\"schema\":\"\",\"name\":\"api\",\"dialect\":\"duckdb\"}],\"dbSelection\":{\"database\":\"\",\"schema\":\"\",\"entityType\":\"table\"}},\"connectionId\":\"c_75e24958-4470-4b13-8fef-a2de1d9fab98\",\"lastSelectedDatabase\":\"\",\"lastSelectedSchema\":\"\",\"datamodelId\":\"\",\"lastSelectedTable\":\"api\",\"config\":{\"metricColumns\":[{\"id\":\"metrics-api-order_id-1753119318387\",\"name\":\"order_id\",\"dataType\":\"VARCHAR\",\"label\":\"Count of Order Id\",\"qualifiedEntityName\":\"api\",\"entityId\":\"api\",\"entityName\":\"api\",\"entityType\":\"table\",\"role\":\"metric\",\"aggregate\":\"COUNT\"}],\"groupByColumns\":[{\"id\":\"groupBy-api-ship_mode-1753119320338\",\"name\":\"ship_mode\",\"dataType\":\"VARCHAR\",\"label\":\"Ship Mode\",\"qualifiedEntityName\":\"api\",\"entityId\":\"api\",\"entityName\":\"api\",\"entityType\":\"table\",\"role\":\"groupby\"}]}},\"lastSelectedDatamodelId\":\"\",\"customCfg\":null}],\"activeCardId\":\"7369f283-3b52-4b6a-b507-e79c1d205000\"}],\"layouts\":{\"lg\":[{\"w\":18,\"h\":36,\"x\":0,\"y\":0,\"i\":\"74a0f4a3-f18b-4fe3-9e30-dbbfd2305485\",\"moved\":false,\"static\":false}]}}]}

Duplicate Dashboard

POST /dashboards/:id/duplicate

Duplicates an existing dashboard, including its template and properties.
The new dashboard will have a new ID, and you can optionally override the title and description.

Request Body (optional):

{
  "title": "My Dashboard (Copy)",
  "description": "A duplicate of my dashboard."
}

If no body is provided, the duplicate will have the original title with "(Copy)" appended and the same description.

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789/duplicate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "My Dashboard (Copy)" }'

Example Response:

{
  "message": "Dashboard duplicated successfully",
  "original": {
    "id": "dashboard_xyz789",
    "title": "My Dashboard"
  },
  "duplicate": {
    "id": "dashboard_newid123",
    "title": "My Dashboard (Copy)",
    "description": "A duplicate of my dashboard.",
    "template": "<stringified-dashboard-template>",
    "permissions": {
      "canEdit": true,
      "canShare": true,
      "canDelete": true
    }
    /* ...other fields... */
  }
}

Get Dashboard by ID

GET /dashboards/:id

Returns details for a specific dashboard, including permissions.

Example Request:

curl -X GET https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "id": "dashboard_xyz789",
  "title": "Sales Dashboard",
  "description": "Quarterly sales KPIs",
  "permissions": {
    "canEdit": true,
    "canShare": true,
    "canDelete": true
  }
  /* ...other fields... */
}

Update Dashboard

PUT /dashboards/:id

Updates dashboard fields (title, description, template, isPrivate, isPublic, version, tenantId).

Request Body:

{
  "title": "Updated Title",
  "description": "Updated description"
}

Example Request:

curl -X PUT https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'

Example Response:

{
  "id": "dashboard_xyz789",
  "title": "Updated Title",
  "description": "Updated description",
  "permissions": {
    /* ... */
  }
}

Delete Dashboard

DELETE /dashboards/:id

Deletes a dashboard by ID.

Example Request:

curl -X DELETE https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "message": "Dashboard deleted successfully"
}

POST /dashboards/:id/share

Shares a dashboard with users or groups.

Request Body:

{
  "shares": [
    {
      "scope": "specific_tenant_user",
      "tenantUserId": "user_456",
      "role": "VIEWER"
    },
    {
      "scope": "all_org_users",
      "role": "EDITOR"
    }
  ]
}

scope options: specific_tenant_user, all_tenant_users, specific_org_user, all_org_users, org_users_only, all_tenants_only
role options: VIEWER, EDITOR, CONTRIBUTOR

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789/share \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "shares": [ { "scope": "all_org_users", "role": "EDITOR" } ] }'

Example Response:

{
  "message": "Dashboard shared successfully",
  "shares": [
    /* ...share entries... */
  ]
}

Remove Dashboard Shares

DELETE /dashboards/:id/share

Removes sharing permissions for specified users/groups.

Request Body:

{
  "shares": [
    {
      "scope": "specific_tenant_user",
      "tenantUserId": "user_456",
      "role": "VIEWER"
    }
  ]
}

Example Request:

curl -X DELETE https://semaphor.cloud/api/management/v1/dashboards/dashboard_xyz789/share \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "shares": [ { "scope": "specific_tenant_user", "tenantUserId": "user_456", "role": "VIEWER" } ] }'

Example Response:

{
  "message": "Dashboard shares removed successfully",
  "removed": [
    /* ...removed entries... */
  ]
}

Error Handling

All endpoints return standard error responses with appropriate HTTP status codes (400, 401, 403, 404, 500, etc.).
Validation errors return details in the response body.

Notes

All endpoints require authentication (Bearer token).
Permission checks are enforced for all operations.
Sharing supports granular roles and scopes for flexible access control.

Dashboards API

On this page