> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update a report by publicId

Idempotent create-or-update ("upsert") of a report keyed by its portable `publicId` — the stable identity for managing dashboards as code (CI/CD pipelines re-applying the same definition against any environment).

If a report with this `publicId` exists in the deployment, it is updated with the fields you send (same semantics as `PUT /reports/:reportId`); otherwise a new report is created with this `publicId`. Re-applying the same request is a no-op. The `publicId` must be a 12-character alphanumeric id (`[0-9A-Za-z]`); mint one client-side when authoring the definition.

This endpoint returns `409` for three different reasons, distinguished by the response body's `code` — handle them differently:

* **No `code`** — the `publicId` already belongs to a report in a **different** deployment. Because `publicId` is unique across the account, it is rejected rather than silently updating across deployments (reported regardless of whether you have access to that report). This is **permanent**: retrying will not help; use a different `publicId`.
* **`code: "upsert_branch_changed"`** — whether this request creates or updates is decided, and access-checked, before it is applied; another writer changed that in between (created or deleted the report with this `publicId`). The request was rejected rather than applied under the wrong permission check. This is **transient: retry the request**. It only happens when two writers target the same `publicId` concurrently, e.g. two pipeline runs applying the same bundle at once.
* **`code: "ambiguous_legacy_id"`** — the id given is one of the ids synthesized for reports that predate stable ids (see below), and it matches more than one of them, so it cannot identify a single report. Nothing was changed. This is **permanent**, and the fix is different from the case above: assign the report you mean a `publicId` of your own with `PUT /deployments/{deploymentId}/reports/{reportId}`, then key on that.

**Reports created before stable ids** do not store a `publicId`; the API synthesizes one for them from the report's internal id. Those synthesized ids are **not unique** — several reports can share one, and in practice most do. This endpoint resolves such an id only when it is unambiguous, adopting it as the report's real `publicId` at that point; otherwise it returns the `ambiguous_legacy_id` conflict above.

For anything you intend to manage as code, do not rely on a synthesized id: give the report a `publicId` you chose. `PUT /deployments/{deploymentId}/reports/{reportId}` accepts `publicId` for exactly this, on any report that does not have one yet (it is write-once — a report's existing `publicId` cannot be changed, since clients may already have stored it).

`source` is **create-only**: it is recorded when the report is first created and ignored on subsequent updates (it describes where the report originated, not its current definition).

Access: updating requires **edit** access to the existing report; creating requires the same access as `POST /reports`.


## OpenAPI

````yaml /api-reference/api.yaml put /api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}
openapi: 3.1.0
info:
  title: Cube Platform API
  version: 1.0.0
  description: >-
    Programmatically manage Cube: deployments and everything scoped to them

    (environments, folders, reports, workbooks, notifications, workspace, and
    agents),

    plus account-level users, groups, policies, embedding, and AI settings.
    Data-model

    authoring, dev mode, branches, and uploads live under /build/api/v1 — same
    host and

    token, routed to the build pods.
servers:
  - url: https://{tenant}.cubecloud.dev
    description: Your tenant host. Replace the whole host if you use a custom domain.
    variables:
      tenant:
        default: your-tenant
        description: Your Cube tenant subdomain
security:
  - bearerAuth: []
tags:
  - name: Deployments
  - name: Deployment Creation
  - name: Environments
  - name: Env Variables
  - name: Regions
  - name: Data Model
  - name: Data Model Uploads
  - name: GitHub
  - name: GitHub Connection
  - name: dbt Sync
  - name: Folders
  - name: Reports
  - name: Workbooks
  - name: Notifications
  - name: Workspace
  - name: Users Admin
  - name: User Attributes
  - name: User Attribute Values
  - name: Tenant Settings
  - name: OAuth Integrations
  - name: User OAuth Tokens
  - name: OIDC Token Configs
  - name: App Theme
  - name: Embed
  - name: Embed Tenants
  - name: Dashboard Embed Access
paths:
  /api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}:
    put:
      tags:
        - Reports
      summary: Create or update a report by publicId
      operationId: upsertReportByPublicId
      parameters:
        - in: path
          name: deploymentId
          required: true
          schema:
            type: number
        - in: path
          name: publicId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReportInput'
        description: CreateReportInput
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
          description: ''
components:
  schemas:
    CreateReportInput:
      properties:
        endResultCell:
          oneOf:
            - type: string
            - type: 'null'
        externalWorkbookId:
          oneOf:
            - type: string
            - type: 'null'
        folderId:
          oneOf:
            - type: integer
            - type: 'null'
        jsonQuery:
          oneOf:
            - type: string
            - type: 'null'
        meta:
          oneOf:
            - additionalProperties: true
              type: object
            - type: 'null'
        name:
          oneOf:
            - type: string
            - type: 'null'
        pivotItems:
          oneOf:
            - $ref: '#/components/schemas/PivotItemsInput'
            - type: 'null'
        publicId:
          oneOf:
            - pattern: ^[0-9A-Za-z]+$
              type: string
              minLength: 12
              maxLength: 12
            - type: 'null'
        resultLocation:
          oneOf:
            - type: string
            - type: 'null'
        source:
          oneOf:
            - $ref: '#/components/schemas/CreateReportInputSource'
            - type: 'null'
        sqlQuery:
          oneOf:
            - type: string
            - type: 'null'
        title:
          oneOf:
            - type: string
            - type: 'null'
        workbookId:
          oneOf:
            - type: integer
            - type: 'null'
      type: object
    Report:
      properties:
        canEdit:
          oneOf:
            - type: boolean
            - type: 'null'
        canManage:
          oneOf:
            - type: boolean
            - type: 'null'
        createdAt:
          oneOf:
            - format: date
              type: string
            - format: date-time
              type: string
        createdBy:
          type: integer
        deploymentId:
          type: integer
        description:
          oneOf:
            - type: string
            - type: 'null'
        endResultCell:
          oneOf:
            - type: string
            - type: 'null'
        externalWorkbookId:
          oneOf:
            - type: string
            - type: 'null'
        externalWorkbookPlacements:
          oneOf:
            - items:
                $ref: '#/components/schemas/ReportPlacement'
              type: array
            - type: 'null'
        folderId:
          oneOf:
            - type: integer
            - type: 'null'
        folderPath:
          items:
            $ref: '#/components/schemas/WorkspaceFolderPathEntry'
          type: array
        id:
          type: integer
        jsonQuery:
          oneOf:
            - type: string
            - type: 'null'
        meta:
          oneOf:
            - additionalProperties: true
              type: object
            - type: 'null'
        name:
          type: string
        pivotItems:
          oneOf:
            - $ref: '#/components/schemas/PivotItems'
            - type: 'null'
        publicId:
          pattern: ^[0-9A-Za-z]+$
          type: string
          minLength: 12
          maxLength: 12
        refreshedBy:
          oneOf:
            - type: integer
            - type: 'null'
        refreshedByUser:
          $ref: '#/components/schemas/ResourceOwner'
        resultLocation:
          oneOf:
            - type: string
            - type: 'null'
        rolesWithAccess:
          oneOf:
            - items:
                $ref: '#/components/schemas/RoleWithAccess'
              type: array
            - type: 'null'
        source:
          oneOf:
            - $ref: '#/components/schemas/ReportDtoSource'
            - type: 'null'
        sqlQuery:
          oneOf:
            - type: string
            - type: 'null'
        title:
          oneOf:
            - type: string
            - type: 'null'
        type:
          $ref: '#/components/schemas/ReportDtoType'
        updatedAt:
          oneOf:
            - format: date
              type: string
            - format: date-time
              type: string
        user:
          $ref: '#/components/schemas/ResourceOwner'
        userId:
          type: integer
        version:
          oneOf:
            - type: integer
            - type: 'null'
        workbookId:
          oneOf:
            - type: integer
            - type: 'null'
      required:
        - publicId
        - userId
        - user
        - name
        - refreshedByUser
        - id
        - deploymentId
        - createdAt
        - updatedAt
        - type
      type: object
    PivotItemsInput:
      properties:
        columns:
          items:
            type: string
          type: array
        filters:
          items:
            type: string
          type: array
        measures:
          items:
            type: string
          type: array
        rows:
          items:
            type: string
          type: array
      required:
        - columns
        - measures
        - rows
        - filters
      type: object
    CreateReportInputSource:
      enum:
        - GOOGLE_SHEETS
        - EXCEL
        - PLAYGROUND
        - D3
      type: string
    ReportPlacement:
      properties:
        endResultCell:
          oneOf:
            - type: string
            - type: 'null'
        resultLocation:
          type: string
        workbookId:
          type: string
      required:
        - workbookId
        - resultLocation
      type: object
    WorkspaceFolderPathEntry:
      properties:
        id:
          type: integer
        name:
          type: string
      required:
        - id
        - name
      type: object
    PivotItems:
      properties:
        columns:
          items:
            type: string
          type: array
        filters:
          items:
            type: string
          type: array
        measures:
          items:
            type: string
          type: array
        rows:
          items:
            type: string
          type: array
      required:
        - columns
        - measures
        - rows
        - filters
      type: object
    ResourceOwner:
      properties:
        email:
          type: string
        firstName:
          oneOf:
            - type: string
            - type: 'null'
        id:
          type: integer
        picture:
          oneOf:
            - type: string
            - type: 'null'
      required:
        - id
        - email
      type: object
    RoleWithAccess:
      properties:
        actions:
          items:
            enum:
              - All
              - DeploymentsManage
              - DeploymentCreate
              - DeploymentRead
              - DeploymentUpdate
              - DeploymentDelete
              - SecretsManage
              - DownloadData
              - PlaygroundRead
              - SchemaRead
              - SchemaUpdate
              - SchemaUpdateDevBranches
              - APMRead
              - PreAggregationBuild
              - AlertsCreate
              - AlertsRead
              - AlertsUpdate
              - AlertsDelete
              - AuditLogManage
              - BillingRead
              - SqlRunnerRead
              - DataAssetsRead
              - DataAssetsManage
              - CubeNetworkConnect
              - ReportRead
              - ReportEdit
              - ReportManage
              - WorkbookManage
              - WorkbookRead
              - WorkbookEdit
              - ChatThreadRead
              - AgentManage
              - AgentRead
              - AgentSpaceManage
              - AgentAdmin
              - DeploymentAgentRead
              - OAuthIntegrationsManage
              - OAuthIntegrationsIssueTokens
              - McpToolsManage
              - AIBIDevelop
              - AIBIExplore
              - AIBIView
              - ChartPalettesManage
              - DashboardThemesManage
              - AIBIDeveloper
              - AIBIUser
              - AIBIViewer
              - EmbedDeploymentRead
              - EmbedDashboardRead
              - FolderRead
              - FolderEdit
              - FolderManage
            type: string
          type: array
        id:
          type: integer
        name:
          type: string
      required:
        - id
        - name
        - actions
      type: object
    ReportDtoSource:
      enum:
        - GOOGLE_SHEETS
        - EXCEL
        - PLAYGROUND
        - D3
      type: string
    ReportDtoType:
      enum:
        - FOLDER
        - WORKBOOK
        - REPORT
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token authentication. Send `Authorization: Bearer <YOUR_TOKEN>`.'

````