Create or update a report by publicId

curl --request PUT \
  --url https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endResultCell": "<string>",
  "externalWorkbookId": "<string>",
  "folderId": 123,
  "jsonQuery": "<string>",
  "meta": {},
  "name": "<string>",
  "pivotItems": {
    "columns": [
      "<string>"
    ],
    "filters": [
      "<string>"
    ],
    "measures": [
      "<string>"
    ],
    "rows": [
      "<string>"
    ]
  },
  "publicId": "<string>",
  "resultLocation": "<string>",
  "sqlQuery": "<string>",
  "title": "<string>",
  "workbookId": 123
}
'

import requests

url = "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}"

payload = {
    "endResultCell": "<string>",
    "externalWorkbookId": "<string>",
    "folderId": 123,
    "jsonQuery": "<string>",
    "meta": {},
    "name": "<string>",
    "pivotItems": {
        "columns": ["<string>"],
        "filters": ["<string>"],
        "measures": ["<string>"],
        "rows": ["<string>"]
    },
    "publicId": "<string>",
    "resultLocation": "<string>",
    "sqlQuery": "<string>",
    "title": "<string>",
    "workbookId": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    endResultCell: '<string>',
    externalWorkbookId: '<string>',
    folderId: 123,
    jsonQuery: '<string>',
    meta: {},
    name: '<string>',
    pivotItems: {
      columns: ['<string>'],
      filters: ['<string>'],
      measures: ['<string>'],
      rows: ['<string>']
    },
    publicId: '<string>',
    resultLocation: '<string>',
    sqlQuery: '<string>',
    title: '<string>',
    workbookId: 123
  })
};

fetch('https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'endResultCell' => '<string>',
    'externalWorkbookId' => '<string>',
    'folderId' => 123,
    'jsonQuery' => '<string>',
    'meta' => [
        
    ],
    'name' => '<string>',
    'pivotItems' => [
        'columns' => [
                '<string>'
        ],
        'filters' => [
                '<string>'
        ],
        'measures' => [
                '<string>'
        ],
        'rows' => [
                '<string>'
        ]
    ],
    'publicId' => '<string>',
    'resultLocation' => '<string>',
    'sqlQuery' => '<string>',
    'title' => '<string>',
    'workbookId' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}"

	payload := strings.NewReader("{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2023-12-25",
  "deploymentId": 123,
  "id": 123,
  "name": "<string>",
  "publicId": "<string>",
  "refreshedByUser": {
    "email": "<string>",
    "id": 123,
    "firstName": "<string>",
    "picture": "<string>"
  },
  "updatedAt": "2023-12-25",
  "user": {
    "email": "<string>",
    "id": 123,
    "firstName": "<string>",
    "picture": "<string>"
  },
  "userId": 123,
  "canEdit": true,
  "canManage": true,
  "createdBy": 123,
  "description": "<string>",
  "endResultCell": "<string>",
  "externalWorkbookId": "<string>",
  "externalWorkbookPlacements": [
    {
      "resultLocation": "<string>",
      "workbookId": "<string>",
      "endResultCell": "<string>"
    }
  ],
  "folderId": 123,
  "folderPath": [
    {
      "id": 123,
      "name": "<string>"
    }
  ],
  "jsonQuery": "<string>",
  "meta": {},
  "pivotItems": {
    "columns": [
      "<string>"
    ],
    "filters": [
      "<string>"
    ],
    "measures": [
      "<string>"
    ],
    "rows": [
      "<string>"
    ]
  },
  "refreshedBy": 123,
  "resultLocation": "<string>",
  "rolesWithAccess": [
    {
      "actions": [],
      "id": 123,
      "name": "<string>"
    }
  ],
  "sqlQuery": "<string>",
  "title": "<string>",
  "version": 123,
  "workbookId": 123
}

PUT

api

deployments

{deploymentId}

reports

by-public-id

{publicId}

Create or update a report by publicId

curl --request PUT \
  --url https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endResultCell": "<string>",
  "externalWorkbookId": "<string>",
  "folderId": 123,
  "jsonQuery": "<string>",
  "meta": {},
  "name": "<string>",
  "pivotItems": {
    "columns": [
      "<string>"
    ],
    "filters": [
      "<string>"
    ],
    "measures": [
      "<string>"
    ],
    "rows": [
      "<string>"
    ]
  },
  "publicId": "<string>",
  "resultLocation": "<string>",
  "sqlQuery": "<string>",
  "title": "<string>",
  "workbookId": 123
}
'

import requests

url = "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}"

payload = {
    "endResultCell": "<string>",
    "externalWorkbookId": "<string>",
    "folderId": 123,
    "jsonQuery": "<string>",
    "meta": {},
    "name": "<string>",
    "pivotItems": {
        "columns": ["<string>"],
        "filters": ["<string>"],
        "measures": ["<string>"],
        "rows": ["<string>"]
    },
    "publicId": "<string>",
    "resultLocation": "<string>",
    "sqlQuery": "<string>",
    "title": "<string>",
    "workbookId": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    endResultCell: '<string>',
    externalWorkbookId: '<string>',
    folderId: 123,
    jsonQuery: '<string>',
    meta: {},
    name: '<string>',
    pivotItems: {
      columns: ['<string>'],
      filters: ['<string>'],
      measures: ['<string>'],
      rows: ['<string>']
    },
    publicId: '<string>',
    resultLocation: '<string>',
    sqlQuery: '<string>',
    title: '<string>',
    workbookId: 123
  })
};

fetch('https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'endResultCell' => '<string>',
    'externalWorkbookId' => '<string>',
    'folderId' => 123,
    'jsonQuery' => '<string>',
    'meta' => [
        
    ],
    'name' => '<string>',
    'pivotItems' => [
        'columns' => [
                '<string>'
        ],
        'filters' => [
                '<string>'
        ],
        'measures' => [
                '<string>'
        ],
        'rows' => [
                '<string>'
        ]
    ],
    'publicId' => '<string>',
    'resultLocation' => '<string>',
    'sqlQuery' => '<string>',
    'title' => '<string>',
    'workbookId' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}"

	payload := strings.NewReader("{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.cubecloud.dev/api/v1/deployments/{deploymentId}/reports/by-public-id/{publicId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"endResultCell\": \"<string>\",\n  \"externalWorkbookId\": \"<string>\",\n  \"folderId\": 123,\n  \"jsonQuery\": \"<string>\",\n  \"meta\": {},\n  \"name\": \"<string>\",\n  \"pivotItems\": {\n    \"columns\": [\n      \"<string>\"\n    ],\n    \"filters\": [\n      \"<string>\"\n    ],\n    \"measures\": [\n      \"<string>\"\n    ],\n    \"rows\": [\n      \"<string>\"\n    ]\n  },\n  \"publicId\": \"<string>\",\n  \"resultLocation\": \"<string>\",\n  \"sqlQuery\": \"<string>\",\n  \"title\": \"<string>\",\n  \"workbookId\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2023-12-25",
  "deploymentId": 123,
  "id": 123,
  "name": "<string>",
  "publicId": "<string>",
  "refreshedByUser": {
    "email": "<string>",
    "id": 123,
    "firstName": "<string>",
    "picture": "<string>"
  },
  "updatedAt": "2023-12-25",
  "user": {
    "email": "<string>",
    "id": 123,
    "firstName": "<string>",
    "picture": "<string>"
  },
  "userId": 123,
  "canEdit": true,
  "canManage": true,
  "createdBy": 123,
  "description": "<string>",
  "endResultCell": "<string>",
  "externalWorkbookId": "<string>",
  "externalWorkbookPlacements": [
    {
      "resultLocation": "<string>",
      "workbookId": "<string>",
      "endResultCell": "<string>"
    }
  ],
  "folderId": 123,
  "folderPath": [
    {
      "id": 123,
      "name": "<string>"
    }
  ],
  "jsonQuery": "<string>",
  "meta": {},
  "pivotItems": {
    "columns": [
      "<string>"
    ],
    "filters": [
      "<string>"
    ],
    "measures": [
      "<string>"
    ],
    "rows": [
      "<string>"
    ]
  },
  "refreshedBy": 123,
  "resultLocation": "<string>",
  "rolesWithAccess": [
    {
      "actions": [],
      "id": 123,
      "name": "<string>"
    }
  ],
  "sqlQuery": "<string>",
  "title": "<string>",
  "version": 123,
  "workbookId": 123
}

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.

Authorizations

Authorization

string

header

required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Path Parameters

deploymentId

number

required

publicId

string

required

Body

application/json

CreateReportInput

endResultCell

string | null

externalWorkbookId

string | null

folderId

integer | null

jsonQuery

string | null

Response

200 - application/json

createdAt

required

deploymentId

integer

required

integer

required

name

string

required

publicId

string

required

Required string length: 12

Pattern: ^[0-9A-Za-z]+$

refreshedByUser

object

required

Show child attributes

type

enum<string>

required

Available options:

FOLDER,

WORKBOOK,

REPORT

updatedAt

required

user

object

required

Show child attributes

userId

integer

required

canEdit

boolean | null

canManage

boolean | null

createdBy

integer

description

string | null

endResultCell

string | null

externalWorkbookId

string | null

externalWorkbookPlacements

object[] | null

Show child attributes

folderId

integer | null

folderPath

object[]

Show child attributes

jsonQuery

string | null

Getting Started

Core Data Endpoints

AI Endpoints

Platform Endpoints

Create or update a report by publicId

Authorizations

Path Parameters

Body

Response