Create a dashboard

Creates a new dashboard in the project. If you omit the template field, an empty dashboard with a default sheet is created automatically. When you provide a template, the required top-level title is applied to that document. A top-level description is also applied when provided; when omitted, the template's own description is preserved. Optional tags classify the dashboard for exact-match discovery and are returned in ascending lexical order.

A Matrix card (matrixTable) whose config.matrix can never render, such as one with an unknown key, an id that isn't a UUID, a totals map that doesn't list every level, or SQL text on the card, is refused with 400 and the errorCode invalid_matrix_cards. details.errors names each card and the path of each problem. A Matrix card with no definition yet, or an unfinished one, is saved. To catch those, and to check field names against your datasets, use Validate a single dashboard.

The caller must have permission to create dashboards in the project. The new dashboard is owned by the authenticated user.

Provide commitMessage to commit the newly created dashboard to the project's connected GitHub repository. When the project requires commits on save, commitMessage is required.

Authorization

BearerAuth

AuthorizationBearer <token>

A project-scoped or dashboard-scoped access token. Generate one via the Token API using your project ID and project secret.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

title*string

Dashboard title (required).

description?string

Optional dashboard description.

template?|

Dashboard template as either a JSON string or an object. If omitted, an empty dashboard with a default sheet is created.

Filters. Send dashboard filters in either shape:

Shape	How filters are written
Filter inputs	One `inputs` entry per filter, with `kind: "filter"`, an `id`, `label`, `variableName`, `scope`, `runtimeScope`, and its own `filter` definition. `scope` sets which sheets and cards the filter reaches (`allSheets`, `sheets`, or `cards`). An `allSheets` scope without `sheetKinds` reaches Document sheets too.
Filter list	A top-level `filters` list, optionally with `inputs` entries that reference those filters. These filters reach regular sheets.

Whichever shape you send, Semaphor stores every filter as an inputs entry and stores the saved default values for those filters in defaultInputValues.

isPublic?boolean

When true, the dashboard is publicly accessible without authentication.

Defaultfalse

tags?array<>

Optional initial dashboard classification. The stored and returned array is sorted in ascending lexical order.

Itemsitems <= 20

commitMessage?string

Commit the created dashboard to GitHub with this message. Required when the target project has commit on save enabled.

Length1 <= length

version?string

Optional version label.

Response Body

`application/json`

curl -X post "https://semaphor.cloud/api/management/v1/dashboards" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'

{
  "versionControl": {
    "status": "committed",
    "commitSha": "string",
    "commitUrl": "http://example.com"
  },
  "id": "string",
  "kind": "string",
  "tags": [
    "string"
  ],
  "title": "string",
  "description": "string",
  "projectId": "string",
  "tenantId": "string",
  "isPrivate": true,
  "isPublic": true,
  "version": "string",
  "permissions": {
    "canEdit": true,
    "canShare": true,
    "canDelete": true
  },
  "ownership": {},
  "isFavorite": true,
  "favoritedAt": "2019-08-24T14:15:22Z"
}

{
  "error": "string",
  "code": "string",
  "errorCode": "string",
  "details": {},
  "success": true
}

{
  "error": "string",
  "code": "string",
  "errorCode": "string",
  "details": {},
  "success": true
}

{
  "error": "string",
  "code": "string",
  "errorCode": "string",
  "details": {},
  "success": true
}

{
  "error": "string",
  "code": "string",
  "errorCode": "string",
  "details": {},
  "success": true
}

{
  "error": "string",
  "errorCode": "COMMIT_FAILED",
  "dashboardSaved": true,
  "dashboard": {
    "id": "string",
    "kind": "string",
    "tags": [
      "string"
    ],
    "title": "string",
    "description": "string",
    "projectId": "string",
    "tenantId": "string",
    "isPrivate": true,
    "isPublic": true,
    "version": "string",
    "permissions": {
      "canEdit": true,
      "canShare": true,
      "canDelete": true
    },
    "ownership": {},
    "isFavorite": true,
    "favoritedAt": "2019-08-24T14:15:22Z"
  },
  "versionControl": {
    "status": "committed",
    "commitSha": "string",
    "commitUrl": "http://example.com"
  }
}

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

409application/json

500application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`