Rename an Embed

{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "embedId is required"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "name cannot be empty"
  }
}

{
  "error": {
    "code": "INVALID_EMBED_ID",
    "message": "Embed configuration not found"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Missing or invalid data app"
  }
}

Rename an Embed

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds/rename \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "embedId": "<string>",
  "name": "<string>",
  "isRenameDashboard": true
}
'

import requests

url = "https://api.usedatabrain.com/api/v2/data-app/embeds/rename"

payload = {
    "embedId": "<string>",
    "name": "<string>",
    "isRenameDashboard": True
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({embedId: '<string>', name: '<string>', isRenameDashboard: true})
};

fetch('https://api.usedatabrain.com/api/v2/data-app/embeds/rename', 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://api.usedatabrain.com/api/v2/data-app/embeds/rename",
  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([
    'embedId' => '<string>',
    'name' => '<string>',
    'isRenameDashboard' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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://api.usedatabrain.com/api/v2/data-app/embeds/rename"

	payload := strings.NewReader("{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.usedatabrain.com/api/v2/data-app/embeds/rename")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usedatabrain.com/api/v2/data-app/embeds/rename")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}"

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

{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "embedId is required"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "name cannot be empty"
  }
}

{
  "error": {
    "code": "INVALID_EMBED_ID",
    "message": "Embed configuration not found"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Missing or invalid data app"
  }
}

{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "embedId is required"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "name cannot be empty"
  }
}

{
  "error": {
    "code": "INVALID_EMBED_ID",
    "message": "Embed configuration not found"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Missing or invalid data app"
  }
}

PUT

api

data-app

embeds

rename

Rename an Embed

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds/rename \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "embedId": "<string>",
  "name": "<string>",
  "isRenameDashboard": true
}
'

import requests

url = "https://api.usedatabrain.com/api/v2/data-app/embeds/rename"

payload = {
    "embedId": "<string>",
    "name": "<string>",
    "isRenameDashboard": True
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({embedId: '<string>', name: '<string>', isRenameDashboard: true})
};

fetch('https://api.usedatabrain.com/api/v2/data-app/embeds/rename', 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://api.usedatabrain.com/api/v2/data-app/embeds/rename",
  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([
    'embedId' => '<string>',
    'name' => '<string>',
    'isRenameDashboard' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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://api.usedatabrain.com/api/v2/data-app/embeds/rename"

	payload := strings.NewReader("{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.usedatabrain.com/api/v2/data-app/embeds/rename")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usedatabrain.com/api/v2/data-app/embeds/rename")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"embedId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"isRenameDashboard\": true\n}"

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

{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "embedId is required"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "name cannot be empty"
  }
}

{
  "error": {
    "code": "INVALID_EMBED_ID",
    "message": "Embed configuration not found"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Missing or invalid data app"
  }
}

Use this endpoint to rename an existing embed. This is useful when you want to improve naming, align with client labels, or clean up your embed catalog without changing permissions or the underlying data.
Optionally, you can also rename the underlying dashboard by setting isRenameDashboard to true.

Endpoint

PUT https://api.usedatabrain.com/api/v2/data-app/embeds/rename

Authentication

All API requests must include your data app API key in the Authorization header. Get your API token when creating a data app – see the data app creation guide for details. For details on managing API tokens, see the API Token guide.

Headers

Authorization

string

required

Bearer token for API authentication. Use your data app API key.

Authorization: Bearer dbn_live_abc123...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

embedId

string

required

The public embed ID you want to rename (for example: "embed-123").
You can retrieve embed IDs from the List All Embeds API or from the embed configuration UI.

name

string

required

The new human‑readable name for the embed configuration.
Must be a non‑empty string.

isRenameDashboard

boolean

Optional flag to also rename the underlying dashboard associated with this embed.
When set to true, DataBrain attempts to update the dashboard’s name to match the new embed name. Defaults to false if omitted.

Example Request

Response

string

The embed ID that was renamed.

name

string

The updated name of the embed configuration.

error

null | object

Error object if the request failed, otherwise null for successful requests.

Example Responses

HTTP Status Code Summary

Status Code	Description
`200`	OK – Embed renamed successfully
`400`	Bad Request – Invalid body, invalid embed ID, or invalid API key
`500`	Internal Server Error – Unexpected server error

Common Error Codes

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing or invalid `embedId` or `name`
`INVALID_EMBED_ID`	400	Embed configuration does not exist
`INVALID_DATA_APP_API_KEY`	400	Missing or invalid data app API key
`INTERNAL_SERVER_ERROR`	500	Unexpected failure on the server

Usage Patterns

Rename for Better UX Labels

// Align embed name with customer-facing label
await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds/rename', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    embedId: 'embed-123',
    name: 'Revenue Overview (ACME)',
  }),
});

Bulk Rename Embeds During Migration

const renames = [
  { embedId: 'embed-001', name: 'Sales Overview' },
  { embedId: 'embed-002', name: 'Marketing Performance' },
];

for (const rename of renames) {
  await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds/rename', {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer dbn_live_abc123...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(rename),
  });
}

Update an Embed

Delete an Embed

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint

Authentication

Headers

Request Body

Example Request

Response

Example Responses

HTTP Status Code Summary

Common Error Codes

Usage Patterns

Rename for Better UX Labels

Bulk Rename Embeds During Migration

​Endpoint

​Authentication

​Headers

​Request Body

​Example Request

​Response

​Example Responses

​HTTP Status Code Summary

​Common Error Codes

​Usage Patterns

​Rename for Better UX Labels

​Bulk Rename Embeds During Migration

​Related APIs

Endpoint

Authentication

Headers

Request Body

Example Request

Response

Example Responses

HTTP Status Code Summary

Common Error Codes

Usage Patterns

Rename for Better UX Labels

Bulk Rename Embeds During Migration

Related APIs