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

# Rename an Embed

> Rename an existing embed and optionally its underlying dashboard, without changing its access settings.

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

```bash theme={"dark"}
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](/guides/datasources/create-a-data-app) for details.

For details on managing API tokens, see the [API Token guide](/developer-docs/helpers/api-token).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your data app API key.

  ```bash theme={"dark"}
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json` for all requests.

  ```bash theme={"dark"}
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="embedId" type="string" required>
  The public embed ID you want to rename (for example: `"embed-123"`).\
  You can retrieve embed IDs from the [List All Embeds](/developer-docs/helpers/api-reference/list-embed) API or from the embed configuration UI.
</ParamField>

<ParamField body="name" type="string" required>
  The new human‑readable name for the embed configuration.\
  Must be a non‑empty string.
</ParamField>

<ParamField body="isRenameDashboard" type="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.
</ParamField>

### Example Request

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/embeds/rename \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "embedId": "embed-123",
        "name": "Executive Sales Overview",
        "isRenameDashboard": true
      }'
    ```

    ```javascript Node.js theme={"dark"}
    const response = 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: 'Executive Sales Overview',
          isRenameDashboard: true,
        }),
      }
    );

    const data = await response.json();
    console.log('Renamed embed:', data.id, '->', data.name);
    ```

    ```python Python theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/embeds/rename"
    headers = {
        "Authorization": "Bearer dbn_live_abc123...",
        "Content-Type": "application/json",
    }
    payload = {
        "embedId": "embed-123",
        "name": "Executive Sales Overview",
    }

    response = requests.put(url, headers=headers, json=payload)
    data = response.json()
    print(f"Renamed embed: {data['id']} -> {data['name']}")
    ```
  </RequestExample>
</Panel>

## Response

<ResponseField name="id" type="string">
  The embed ID that was renamed.
</ResponseField>

<ResponseField name="name" type="string">
  The updated name of the embed configuration.
</ResponseField>

<ResponseField name="error" type="null | object">
  Error object if the request failed, otherwise `null` for successful requests.
</ResponseField>

### Example Responses

<Panel>
  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "id": "embed-123",
      "name": "Executive Sales Overview",
      "error": null
    }
    ```

    ```json 400 - Validation Error theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "embedId is required"
      }
    }
    ```

    ```json 400 - Invalid Name theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "name cannot be empty"
      }
    }
    ```

    ```json 400 - Invalid Embed ID theme={"dark"}
    {
      "error": {
        "code": "INVALID_EMBED_ID",
        "message": "Embed configuration not found"
      }
    }
    ```

    ```json 400 - Invalid API Key theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "Missing or invalid data app"
      }
    }
    ```
  </ResponseExample>
</Panel>

## 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

```javascript theme={"dark"}
// 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

```javascript theme={"dark"}
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),
  });
}
```

## Related APIs

* [Embed a Pre-built Dashboard/Metric](/developer-docs/helpers/api-reference/create-embed)
* [Create an Empty Dashboard Embed](/developer-docs/helpers/api-reference/create-dashboard-embed)
* [Update an Embed](/developer-docs/helpers/api-reference/update-embed)
* [Delete an Embed](/developer-docs/helpers/api-reference/delete-embed)
* [List All Embeds](/developer-docs/helpers/api-reference/list-embed)