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

# Update Data App

> Update the name and settings of an existing Data App.

Update the name and configuration of an existing Data App. This is useful for renaming Data Apps or updating their settings.

<Note>
  Updating a Data App name will not affect existing embed configurations or API tokens. They will continue to work with the renamed Data App.
</Note>

<Warning>
  **Authentication Requirement:** This endpoint requires a **service token** (not a data app API key). Service tokens have elevated permissions to manage Data Apps across your organization.
</Warning>

## Endpoint Formats

<Tabs>
  <Tab title="New Endpoint (Recommended)">
    ```
    PUT https://api.usedatabrain.com/api/v2/data-app
    ```

    **Use this endpoint** for all new integrations. This is the recommended endpoint format.
  </Tab>

  <Tab title="Legacy Endpoint (Deprecated Soon)">
    ```
    PUT https://api.usedatabrain.com/api/v2/dataApp
    ```

    This endpoint still works but will be deprecated. Please migrate to the new endpoint format.
  </Tab>
</Tabs>

## Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions.

To access your service token:

1. In **Settings** page, navigate to the **Service Tokens** section.
2. Click the **"Generate Token"** button to create a new service token if you don't have one already.

Use this token as the Bearer value in your Authorization header.

## Headers

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

  ```
  Authorization: Bearer service_token_xyz...
  ```
</ParamField>

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

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  The current name of the Data App to update. This must exactly match an existing Data App name.

  <Expandable title="Finding Data App names">
    * Use the [List Data Apps](/developer-docs/helpers/api-reference/list-data-apps) API to get all Data App names
    * Check your Databrain dashboard for Data App configurations
    * The name is case-sensitive
  </Expandable>
</ParamField>

<ParamField body="updateName" type="string" required>
  The new name for the Data App. This name must be unique within your organization.

  <Expandable title="Naming guidelines">
    * Names must be unique within your organization
    * Use descriptive names that indicate the purpose (e.g., "Customer Portal Analytics", "Partner Dashboard")
    * Avoid special characters that might cause URL encoding issues
  </Expandable>
</ParamField>

## Response

<ResponseField name="name" type="string">
  The updated name of the Data App.
</ResponseField>

<ResponseField name="error" type="object">
  Error object returned only when the request fails. Not included in successful responses.

  <Expandable title="error properties">
    <ResponseField name="code" type="string">
      Error code identifying the type of error.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message describing what went wrong.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app \
      --header 'Authorization: Bearer service_token_xyz...' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Customer Analytics",
        "updateName": "Updated Customer Analytics"
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app', {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer service_token_xyz...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Customer Analytics',
        updateName: 'Updated Customer Analytics'
      })
    });

    const data = await response.json();
    console.log('Updated Data App:', data.name);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app"
    headers = {
        "Authorization": "Bearer service_token_xyz...",
        "Content-Type": "application/json"
    }
    payload = {
        "name": "Customer Analytics",
        "updateName": "Updated Customer Analytics"
    }

    response = requests.put(url, headers=headers, json=payload)
    data = response.json()
    print(f"Updated Data App: {data['name']}")
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;

    public class UpdateDataApp {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String requestBody = """
                {
                    "name": "Customer Analytics",
                    "updateName": "Updated Customer Analytics"
                }""";
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.usedatabrain.com/api/v2/data-app"))
                .header("Authorization", "Bearer service_token_xyz...")
                .header("Content-Type", "application/json")
                .PUT(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
                
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
                
            System.out.println("Response: " + response.body());
        }
    }
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
    )

    type UpdateDataAppRequest struct {
        Name       string `json:"name"`
        UpdateName string `json:"updateName"`
    }

    type UpdateDataAppResponse struct {
        Name  string      `json:"name"`
        Error interface{} `json:"error"`
    }

    func main() {
        requestBody := UpdateDataAppRequest{
            Name:       "Customer Analytics",
            UpdateName: "Updated Customer Analytics",
        }

        jsonData, _ := json.Marshal(requestBody)
        
        req, _ := http.NewRequest("PUT", "https://api.usedatabrain.com/api/v2/data-app", bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer service_token_xyz...")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var result UpdateDataAppResponse
        json.NewDecoder(resp.Body).Decode(&result)
        fmt.Printf("Updated Data App: %s\n", result.Name)
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $curl = curl_init();

    $data = [
        'name' => 'Customer Analytics',
        'updateName' => 'Updated Customer Analytics'
    ];

    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/data-app',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => 'PUT',
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer service_token_xyz...',
            'Content-Type: application/json'
        ],
    ]);

    $response = curl_exec($curl);
    curl_close($curl);

    $result = json_decode($response, true);
    echo 'Updated Data App: ' . $result['name'];
    ?>
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Put.new(uri)
    request['Authorization'] = 'Bearer service_token_xyz...'
    request['Content-Type'] = 'application/json'

    request.body = {
      name: 'Customer Analytics',
      updateName: 'Updated Customer Analytics'
    }.to_json

    response = http.request(request)
    result = JSON.parse(response.body)
    puts "Updated Data App: #{result['name']}"
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "name": "Updated Customer Analytics"
    }
    ```

    ```json 400 - Invalid Request Body theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"updateName\" is required"
      }
    }
    ```

    ```json 400 - Data App Not Found theme={"dark"}
    {
      "error": {
        "code": "DATA_APP_NOT_FOUND",
        "message": "Data app not found"
      }
    }
    ```

    ```json 400 - Invalid Service Token theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Invalid Service Token"
      }
    }
    ```

    ```json 500 - Internal Server Error theme={"dark"}
    {
      "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "INTERNAL_SERVER_ERROR"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                       |
| ----------- | ------------------------------------------------- |
| `200`       | **OK** - Data App updated successfully            |
| `400`       | **Bad Request** - Invalid request parameters      |
| `500`       | **Internal Server Error** - Server error occurred |

## Possible Errors

| Error Code              | HTTP Status | Description                            |
| ----------------------- | ----------- | -------------------------------------- |
| `INVALID_REQUEST_BODY`  | 400         | Missing or invalid parameters          |
| `DATA_APP_NOT_FOUND`    | 400         | Data App with specified name not found |
| `AUTHENTICATION_ERROR`  | 400         | Invalid or missing service token       |
| `INTERNAL_SERVER_ERROR` | 500         | Server error                           |

## Quick Start Guide

<Steps>
  <Step title="Get your service token">
    In **Settings** page, navigate to the **Service Tokens** section. Click the **"Generate Token"** button to create a new service token if you don't have one already.
  </Step>

  <Step title="Identify the Data App">
    Use the [List Data Apps](/developer-docs/helpers/api-reference/list-data-apps) API to verify the current Data App configuration:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app' \
      --header 'Authorization: Bearer service_token_xyz...'
    ```
  </Step>

  <Step title="Update the Data App">
    Make a PUT request with the current name and the new name:

    ```bash theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app \
      --header 'Authorization: Bearer service_token_xyz...' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Current Data App Name",
        "updateName": "New Data App Name"
      }'
    ```
  </Step>

  <Step title="Verify the update">
    List Data Apps again to confirm the update:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app' \
      --header 'Authorization: Bearer service_token_xyz...'
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="List Data Apps" icon="list" href="/developer-docs/helpers/api-reference/list-data-apps">
    View all Data Apps in your organization
  </Card>

  <Card title="Create Data App" icon="plus" href="/developer-docs/helpers/api-reference/create-data-app">
    Create new Data Apps for your organization
  </Card>

  <Card title="Delete Data App" icon="trash" href="/developer-docs/helpers/api-reference/delete-data-app">
    Remove Data Apps you no longer need
  </Card>

  <Card title="Create API Token" icon="key" href="/developer-docs/helpers/api-reference/create-api-token">
    Generate API tokens for your Data Apps
  </Card>
</CardGroup>