> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# App API

The App API lets you view and update an existing Branch app configuration to better support workflows.

[Read the App API overview](https://help.branch.io/apidocs/app/overview.md)

## Get current Branch app configuration

`GET https://api2.branch.io/v1/app/{branch_key}`

This endpoint retrieves all app-related configurations for the requested branch.

### Parameters

- `branch_key` (string, path, required) — The Branch Key of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).
- `branch_secret` (string, query, required) — The Branch Secret of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).

### Responses

- `200` — Success.
- `400` — Bad request—typically an invalid or missing credential or parameter.
- `429` — Rate limit exceeded—reduce request frequency and retry.

### Returns

Success. Returns `400` and `429` on failure — see the response panel for the error shape.

### Example request

```bash
curl 'https://api2.branch.io/v1/app/key_live_xxxx?branch_secret=secret_live_xxxx' \
  --request GET
```

### Example responses

`200`

```json
{
  "alternate_short_url_domain": "branch-alternate.app.link",
  "always_open_app": 1,
  "android_cd_enabled": false,
  "android_cd_hashed": "",
  "android_tablet_url": "",
  "auto_fetch": false,
  "deepview_configs": {
    "ios": {
      "enabled": true,
      "clipboard_deepview": "branch_clipboard_deepview",
      "deepview_audience_id": 0
    },
    "android": {
      "enabled": true,
      "clipboard_deepview": "branch_clipboard_deepview",
      "deepview_audience_id": 0
    }
  },
  "default_short_url_domain": "branch.app.link",
  "desktop_uri_scheme": "",
  "esp_config": {
    "map_query_params_to_deep_link_data": [
      ""
    ],
    "secrets": [
      ""
    ],
    "strip_protocol_from_deeplink_path": false,
    "email_enabled": false,
    "strip_protocol_from_android_deeplink_path": false,
    "default_to_open_for_android_deeplink_path": false,
    "append_full_url_for_key": "$canonical_url",
    "append_all_params": true,
    "ads_enabled": false,
    "append_path_for_key": "",
    "strip_protocol_from_ios_deeplink_path": false,
    "has_confirmed": true
  },
  "imei_collection_enabled": false,
  "imei_terms_and_conditions": "",
  "ios_bundle_settings": "",
  "ios_additional_bundle_ids": [
    "com.test"
  ],
  "ios_cd_enabled": false,
  "ios_cd_hashed": "",
  "ipad_url": "",
  "ios_app_store_id": "",
  "map_utm_params": "",
  "reserved_analytics_to_utm": "",
  "origin": "",
  "sitemap_enabled": "",
  "tmta_enabled": "",
  "wechat_url": "",
  "redirect_domains_whitelist": [
    ""
  ],
  "journeys_open_app": "",
  "passive_deepview_ios": "",
  "passive_deepview_android": "",
  "uri_redirect_mode": 1,
  "timezone": "America/Los_Angeles",
  "mac_uri_scheme": "branch-example-mac://",
  "mac_store_url": "",
  "windows_uri_scheme": "examplebranchsdk://",
  "windows_store_url": "",
  "windows_package_family_name": "",
  "organization_id": "",
  "sk_ad_network_enabled": "",
  "ios_app_store_id_verified": false,
  "local_currency": "",
  "organic_search_domains": [
    ""
  ],
  "id": "00000000",
  "app_key": "00000000",
  "zuora_account_id": "",
  "branch_key": "key_live_xxxx",
  "branch_secret": "secret_live_xxxx",
  "creation_date": "2019-06-19T19:37:31.887Z",
  "app_name": "My App Name",
  "dev_name": "First Last",
  "dev_email": "test@branch.io",
  "dev_phone_number": "",
  "android_app": 0,
  "android_url": "",
  "android_uri_scheme": "",
  "android_package_name": "",
  "sha256_cert_fingerprints": [
    ""
  ],
  "android_app_links_enabled": false,
  "ios_app": 0,
  "ios_url": "",
  "ios_uri_scheme": "",
  "ios_store_country": "US",
  "ios_bundle_id": "com.test.app",
  "ios_team_id": "0000XXXX",
  "universal_linking_enabled": "",
  "fire_url": "",
  "windows_phone_url": "",
  "blackberry_url": "",
  "web_url": "https://branch.io",
  "default_desktop_url": "http://branch.io",
  "short_url_domain": "",
  "text_message": "",
  "og_app_id": "",
  "og_title": "Branch Monster Factory",
  "og_image_url": "",
  "og_description": "",
  "deepview_desktop": "",
  "deepview_ios": "",
  "deepview_android": ""
}
```

`400`

```json
{
  "error": {
    "message": "Authentication failed.",
    "code": 400
  }
}
```

`429`

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit reached."
  }
}
```

## Update Branch app configuration

`PUT https://api2.branch.io/v1/app/{branch_key}`

Updates an existing Branch app configuration. Any parameters included in the request body are updated to the provided values.

### Parameters

- `branch_key` (string, path, required) — The Branch Key of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).
- `branch_secret` (string, required) — The Branch Secret of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).
- `dev_email` (string, required) — The main contact developer email (max 255 characters).
- `always_open_app` (enum) — Indicates whether to try to open the app on link click or not. One of `0`, `1`.
- `android_app` (enum) — Whether an Android app is enabled. 0 is for disabled. 1 is for enabled. One of `0`, `1`.
- `android_app_links_enabled` (enum) — Whether App Links are enabled. One of `true`, `false`.
- `android_cd_enabled` (boolean) — Indicates whether Content Discovery (CD) is enabled for Android.
- `android_cd_hashed` (string) — Android CD hash details.
- `android_package_name` (string) — The Android package name.
- `android_tablet_url` (string) — URL specific to Android tablets.
- `android_uri_scheme` (string) — The Android URI scheme.
- `android_url` (string) — URL of Android store, or namespace (com.android.myapp).
- `app_name` (string) — Name of the app.
- `auto_fetch` (boolean) — Details auto-fetching flag.
- `blackberry_url` (string) — The redirect on BlackBerry phones.
- `creation_date` (string) — Date app was created.
- `deepview_android` (string) — The current deepview selected for the Android platform.
- `deepview_configs` (object) — Android and iOS configurations related to deepviews.
- `deepview_configs.ios` (object) — iOS-related deepview configurations.
- `deepview_configs.ios.enabled` (boolean) — Indicates whether iOS-related configurations are enabled.
- `deepview_configs.ios.clipboard_deepview` (string) — Deepview details.
- `deepview_configs.ios.deepview_audience_id` (integer) — Unique deepview ID.
- `deepview_configs.android` (object) — Android-related deepview configurations.
- `deepview_configs.android.enabled` (boolean) — Indicates whether Android-related configurations are enabled.
- `deepview_configs.android.clipboard_deepview` (string) — Deepview details.
- `deepview_configs.android.deepview_audience_id` (integer) — Unique deepview ID.
- `deepview_desktop` (string) — The current deepview selected for the desktop platform.
- `deepview_ios` (string) — The current deepview selected for the iOS platform.
- `default_desktop_url` (string) — The default desktop redirect, or null if set to hosted SMS.
- `default_short_url_domain` (string) — Short URL to the default domain.
- `desktop_uri_scheme` (string) — Standard URI scheme if available.
- `dev_name` (string) — Main contact name.
- `dev_phone_number` (string) — Main contact phone.
- `esp_config` (object) — Specific configurations for email service providers.
- `esp_config.map_query_params_to_deep_link_data` (array of string)
- `esp_config.secrets` (array of string)
- `esp_config.strip_protocol_from_deeplink_path` (boolean)
- `esp_config.email_enabled` (boolean)
- `esp_config.strip_protocol_from_android_deeplink_path` (boolean)
- `esp_config.default_to_open_for_android_deeplink_path` (boolean)
- `esp_config.append_full_url_for_key` (string)
- `esp_config.append_all_params` (boolean)
- `esp_config.ads_enabled` (boolean)
- `esp_config.append_path_for_key` (string)
- `esp_config.strip_protocol_from_ios_deeplink_path` (boolean)
- `esp_config.has_confirmed` (boolean)
- `fire_url` (string) — The redirect on Fire phones.
- `imei_collection_enabled` (boolean) — Indicates whether IMEI collection is enabled.
- `imei_terms_and_conditions` (string) — IMEI terms and conditions if available.
- `ios_additional_bundle_ids` (array of string) — Additional iOS Bundle IDs.
- `ios_app` (integer) — Whether an iOS app is enabled.
- `ios_app_store_id` (string) — Application ID specific to iOS.
- `ios_app_store_id_verified` (boolean) — Identifies if the iOS App Store ID is verified officially.
- `ios_bundle_id` (string) — The iOS Bundle ID.
- `ios_bundle_settings` (string) — iOS settings.
- `ios_cd_enabled` (boolean) — Indicates whether Content Discovery (CD) is enabled for iOS.
- `ios_cd_hashed` (string) — iOS CD hash details.
- `ios_store_country` (string) — The country code of the app. Defaults to US.
- `ios_team_id` (string) — The iOS Team ID.
- `ios_uri_scheme` (string) — The iOS URI scheme.
- `ios_url` (string) — URL of iOS store, or app ID (id00000000).
- `ipad_url` (string) — iPad URL associated with the request.
- `journeys_open_app` (string)
- `mac_store_url` (string) — Mac Store valid URL if available.
- `mac_uri_scheme` (string) — Mac URI scheme.
- `map_utm_params` (string)
- `og_app_id` (string) — Optional default Open Graph (OG) app ID.
- `og_description` (string) — Optional default OG description.
- `og_image_url` (string) — Optional default OG image URL.
- `og_title` (string) — Optional default OG title.
- `organic_search_domains` (array of string) — Search domains.
- `origin` (string) — Request origin.
- `passive_deepview_android` (string)
- `passive_deepview_ios` (string)
- `redirect_domains_whitelist` (array of string) — Allowlist URLs for redirection.
- `reserved_analytics_to_utm` (string)
- `sha256_cert_fingerprints` (array of string) — The SHA256 fingerprints for App Links.
- `sitemap_enabled` (string) — Indicates whether Content Discovery (CD) is enabled for Android.
- `text_message` (string) — Text message to use, where {{ link }} is replaced with the short link.
- `timezone` (string) — Request time zone.
- `universal_linking_enabled` (string) — Whether Universal Links are enabled.
- `uri_redirect_mode` (integer) — URI redirection mode.
- `web_url` (string) — Backup website if URLs are null.
- `wechat_url` (string) — WeChat URL against the request.
- `windows_package_family_name` (string)
- `windows_phone_url` (string) — The redirect on Windows phones.
- `windows_store_url` (string) — Windows Store valid URL if available.
- `windows_uri_scheme` (string)

### Responses

- `200` — Success.
- `400` — Bad request—typically an invalid or missing credential or parameter.
- `429` — Rate limit exceeded—reduce request frequency and retry.

### Returns

Success. Returns `400` and `429` on failure — see the response panel for the error shape.

### Example request

```bash
curl 'https://api2.branch.io/v1/app/key_live_xxxx' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_secret": "secret_live_xxxx",
    "dev_email": "test@branch.io",
    "deepview_configs": {
      "ios": {
        "enabled": true,
        "clipboard_deepview": "branch_clipboard_deepview"
      },
      "android": {
        "enabled": true,
        "clipboard_deepview": "branch_clipboard_deepview"
      }
    },
    "default_short_url_domain": "branch.app.link",
    "esp_config": {
      "append_full_url_for_key": "https://example.com/sample-page/",
      "append_all_params": true,
      "has_confirmed": true
    },
    "ios_additional_bundle_ids": [
      "com.test"
    ],
    "uri_redirect_mode": 1,
    "timezone": "America/Los_Angeles",
    "mac_uri_scheme": "branch-example-mac",
    "windows_uri_scheme": "examplebranchsdk",
    "creation_date": "2019-06-19T19:37:31.887Z",
    "app_name": "My App Name",
    "dev_name": "First Last",
    "ios_store_country": "US",
    "ios_bundle_id": "com.test.app",
    "ios_team_id": "0000XXXX",
    "web_url": "https://branch.io",
    "default_desktop_url": "http://branch.io",
    "og_title": "Branch Monster Factory"
  }'
```

### Example responses

`200`

```json
{
  "alternate_short_url_domain": "branch-alternate.app.link",
  "always_open_app": 1,
  "android_cd_enabled": false,
  "android_cd_hashed": "",
  "android_tablet_url": "",
  "auto_fetch": false,
  "deepview_configs": {
    "ios": {
      "enabled": true,
      "clipboard_deepview": "branch_clipboard_deepview",
      "deepview_audience_id": 0
    },
    "android": {
      "enabled": true,
      "clipboard_deepview": "branch_clipboard_deepview",
      "deepview_audience_id": 0
    }
  },
  "default_short_url_domain": "branch.app.link",
  "desktop_uri_scheme": "",
  "esp_config": {
    "map_query_params_to_deep_link_data": [
      ""
    ],
    "secrets": [
      ""
    ],
    "strip_protocol_from_deeplink_path": false,
    "email_enabled": false,
    "strip_protocol_from_android_deeplink_path": false,
    "default_to_open_for_android_deeplink_path": false,
    "append_full_url_for_key": "$canonical_url",
    "append_all_params": true,
    "ads_enabled": false,
    "append_path_for_key": "",
    "strip_protocol_from_ios_deeplink_path": false,
    "has_confirmed": true
  },
  "imei_collection_enabled": false,
  "imei_terms_and_conditions": "",
  "ios_bundle_settings": "",
  "ios_additional_bundle_ids": [
    "com.test"
  ],
  "ios_cd_enabled": false,
  "ios_cd_hashed": "",
  "ipad_url": "",
  "ios_app_store_id": "",
  "map_utm_params": "",
  "reserved_analytics_to_utm": "",
  "origin": "",
  "sitemap_enabled": "",
  "tmta_enabled": "",
  "wechat_url": "",
  "redirect_domains_whitelist": [
    ""
  ],
  "journeys_open_app": "",
  "passive_deepview_ios": "",
  "passive_deepview_android": "",
  "uri_redirect_mode": 1,
  "timezone": "America/Los_Angeles",
  "mac_uri_scheme": "branch-example-mac://",
  "mac_store_url": "",
  "windows_uri_scheme": "examplebranchsdk://",
  "windows_store_url": "",
  "windows_package_family_name": "",
  "organization_id": "",
  "sk_ad_network_enabled": "",
  "ios_app_store_id_verified": false,
  "local_currency": "",
  "organic_search_domains": [
    ""
  ],
  "id": "00000000",
  "app_key": "00000000",
  "zuora_account_id": "",
  "branch_key": "key_live_xxxx",
  "branch_secret": "secret_live_xxxx",
  "creation_date": "2019-06-19T19:37:31.887Z",
  "app_name": "My App Name",
  "dev_name": "First Last",
  "dev_email": "test@branch.io",
  "dev_phone_number": "",
  "android_app": 0,
  "android_url": "",
  "android_uri_scheme": "",
  "android_package_name": "",
  "sha256_cert_fingerprints": [
    ""
  ],
  "android_app_links_enabled": false,
  "ios_app": 0,
  "ios_url": "",
  "ios_uri_scheme": "",
  "ios_store_country": "US",
  "ios_bundle_id": "com.test.app",
  "ios_team_id": "0000XXXX",
  "universal_linking_enabled": "",
  "fire_url": "",
  "windows_phone_url": "",
  "blackberry_url": "",
  "web_url": "https://branch.io",
  "default_desktop_url": "http://branch.io",
  "short_url_domain": "",
  "text_message": "",
  "og_app_id": "",
  "og_title": "Branch Monster Factory",
  "og_image_url": "",
  "og_description": "",
  "deepview_desktop": "",
  "deepview_ios": "",
  "deepview_android": ""
}
```

`400`

```json
{
  "error": {
    "message": "Authentication failed.",
    "code": 400
  }
}
```

`429`

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit reached."
  }
}
```