Skip to main content
{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}
PUT
/
api
/
v2
/
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
}
'
{
  "id": "embed-123",
  "name": "Executive Sales Overview",
  "error": null
}
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

​
id
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 CodeDescription
200OK – Embed renamed successfully
400Bad Request – Invalid body, invalid embed ID, or invalid API key
500Internal Server Error – Unexpected server error

​
Common Error Codes

Error CodeHTTP StatusDescription
INVALID_REQUEST_BODY400Missing or invalid embedId or name
INVALID_EMBED_ID400Embed configuration does not exist
INVALID_DATA_APP_API_KEY400Missing or invalid data app API key
INTERNAL_SERVER_ERROR500Unexpected 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),
  });
}