Skip to main content
PUT
Create or update a workbook by slug
Idempotent create-or-update (“upsert”) of a workbook keyed by its deployment-scoped slug — the portable identity for managing dashboards as code (CI/CD pipelines re-applying the same definition against any environment). If a workbook with this slug exists in the deployment, it is updated: only the fields you send are changed, and meta is merged into the existing metadata (a meta.dashboardDraft is validated like everywhere else). Otherwise a new workbook is created with this slug. The slug is normalized (trimmed, lowercased) before matching. Re-applying the same request is a no-op. Access: updating requires edit access to the workbook holding the slug (requests that include folderId require manage access, plus edit access to the destination folder); creating requires the same access as POST /workbooks (AI BI User role or higher). Whether this request creates or updates is decided — and access-checked — before it is applied. If another writer changes that in between (creates or deletes the workbook holding this slug), the request is rejected with 409 and code: "upsert_branch_changed" rather than applied under the wrong permission check. This is transient: retry the request. It only happens when two writers target the same slug concurrently — for example two pipeline runs applying the same bundle at once, where one creates the workbook and the other must then retry into the update path. Returns 404 if the deployment does not exist.

Authorizations

Authorization
string
header
required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Path Parameters

deploymentId
number
required
slug
string
required

Body

application/json

CreateWorkbookInput

folderId
number | null
meta
object | null
name
string | null

Response

200 - application/json
calculatedFields
object
required
createdAt
required
deploymentId
integer
required
id
integer
required
meta
object
required
name
string
required
type
enum<string>
required
Available options:
FOLDER,
WORKBOOK,
REPORT
updatedAt
required
createdBy
integer
dashboardDraft
object | null
dashboardPublished
object | null
folderId
number | null
folderPath
object[]
isFavorite
boolean | null
publishedDashboard
object | null
slug
string | null
user
object | null
userId
number | null