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

# App Build Upload API

> Upload mobile builds or web app URLs programmatically via the API

These endpoints allow you to upload mobile app builds or web app URLs programmatically. For most use cases, we recommend using our [GitHub Action](/docs/ci-cd-integration.md) instead.

All requests require an API key in the `X-API-Key` header. See [API Reference](/docs/api-reference.md) for authentication details.

***

> [tab] Mobile (iOS/Android)
>
> ## Endpoints Overview
>
> | Endpoint | Platform | Description |
> | - | - | - |
> | [Start Upload](#start-upload) | iOS, Android | Get a presigned URL to upload a build file |
> | [Confirm Upload](#confirm-upload) | iOS, Android | Finalize a mobile build upload |
>
> ## Start Upload
>
> Initiate an app build upload and get a presigned URL for uploading your build file.
>
> > [!NOTE]
> >
> > **POST** `/api/ci/start-upload` — Returns `200 OK`
>
> ### Request Body
>
> **bundle\_id** `string` *required*
>
> Your app's bundle identifier (e.g., `com.company.app`)
>
> **platform** `string` *required*
>
> Target platform: `ios` or `android`
>
> **filename** `string` *required*
>
> Name of the build file (e.g., `app-release.apk` or `MyApp.zip`)
>
> **name** `string`
>
> Display name for your app. Used when the app is created, and updates the name if the app already exists with a different one.
>
> **app\_id** `string`
>
> Custom identifier that keeps several apps with the same bundle ID in one environment, for example one app per release version (`v7.12.0`). The app is created the first time an `app_id` is used. Up to 64 characters: lowercase letters, numbers, dots, hyphens, and underscores. It must start and end with a letter or number, with no two separators in a row. If omitted, the build goes to the app identified by bundle ID alone. Passing your bundle ID as `app_id` is the same as leaving it out, and the format rule does not apply to it.
>
> **environment** `string`
>
> Environment name to associate this app with (e.g., `staging`, `production`). Apps with the same bundle ID but different environments are treated as separate apps. Must match an existing environment in your organization. If omitted, the app is assigned to your default environment.
>
> ### Example Request
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/ci/start-upload \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "com.company.app",
>     "platform": "android",
>     "filename": "app-release.apk"
>   }'
> ```
>
> ### Response Fields
>
> **upload\_url** `string`
>
> Presigned URL for uploading your build file via PUT request. Valid for 1 hour.
>
> **file\_path** `string`
>
> Storage path of the uploaded file. Pass this to the confirm-upload endpoint.
>
> ### Example Response
>
> ```json theme={null}
> {
>   "upload_url": "https://storage.supabase.co/...",
>   "file_path": "app-uuid/android/app-release-20250115T103000.apk"
> }
> ```
>
> After receiving the response, upload your build file to the `upload_url` using a PUT request:
>
> ```bash theme={null}
> curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
>   -H "Content-Type: application/octet-stream" \
>   --data-binary @./path/to/your/app.apk
> ```
>
> ***
>
> ## Confirm Upload
>
> After uploading your build file, call this endpoint to finalize the upload and trigger any configured automations.
>
> > [!NOTE]
> >
> > **POST** `/api/ci/confirm-upload` — Returns `200 OK`
>
> ### Request Body
>
> **bundle\_id** `string` *required*
>
> Your app's bundle identifier (must match the one used in start-upload)
>
> **platform** `string` *required*
>
> Target platform: `ios` or `android`
>
> **uploaded\_file\_path** `string` *required*
>
> The `file_path` returned from the start-upload response
>
> **app\_id** `string`
>
> Custom app identifier. Must match the value used in start-upload. Leaving it out and passing your bundle ID count as the same value. A mismatch is rejected.
>
> **name** `string`
>
> Display name for your app (e.g., "My Android App"). If the app already exists and the name differs, it will be updated.
>
> **environment** `string`
>
> Environment name (must match the value used in start-upload). Used to look up the correct app when multiple apps share the same bundle ID.
>
> **commit\_sha** `string`
>
> Git commit SHA for tracking which commit this build came from. Send the full 40-character SHA if you want runs of this build to [use your flows at its commit](/docs/api-runs.md#branch-builds-run-at-their-commit).
>
> **branch\_name** `string`
>
> Git branch name. Displayed in the BugRadar UI for build identification.
>
> **repo\_full\_name** `string`
>
> Repository name in `org/repo` format (e.g., `myorg/myrepo`). Required for [GitHub Bot](/docs/github-integration.md) integration — links this build to your repository so the bot can find it when processing PRs.
>
> **variables** `string | object`
>
> Key-value variables to attach to this build. Available in flow instructions via `${env:KEY}`. Accepts a string (`"KEY1=VALUE1,KEY2=VALUE2"`) or a JSON object (`{"KEY1": "VALUE1"}`). See [Build Variables](/docs/variables.md#build-variables).
>
> **enable\_ios\_keychain\_access\_group\_remapping** `boolean`
>
> iOS `.ipa` only. Persists the app preference and instruments the IPA so Team-ID-prefixed keychain access groups keep working after cloud device re-signing. When omitted, the app's saved preference is used.
>
> **location** `string`
>
> Optional. Two-letter ISO country code, such as `MX`. Every run this upload starts sends its device traffic from that country. Android only: an iOS upload with a location is refused. See [Proxy location](/docs/run-location.md).
>
> **locale** `string`
>
> Optional. Language and region, such as `de-DE`, that every run this upload starts opens the app in. Android and iOS. See [Language & region](/docs/language-and-region.md).
>
> ### Example Request
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/ci/confirm-upload \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "com.company.app",
>     "platform": "ios",
>     "uploaded_file_path": "app-uuid/ios/MyApp-20250115T103000.ipa",
>     "name": "My iOS App",
>     "environment": "staging",
>     "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
>     "branch_name": "feature/new-login",
>     "repo_full_name": "myorg/myrepo",
>     "enable_ios_keychain_access_group_remapping": true,
>     "variables": "PR_NUMBER=42,BRANCH=feature/new-login"
>   }'
> ```
>
> Android / non-IPA uploads omit `enable_ios_keychain_access_group_remapping`:
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/ci/confirm-upload \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "com.company.app",
>     "platform": "android",
>     "uploaded_file_path": "app-uuid/android/app-release-20250115T103000.apk",
>     "name": "My Android App",
>     "environment": "staging",
>     "variables": "PR_NUMBER=42,BRANCH=feature/new-login"
>   }'
> ```
>
> ### Response Fields
>
> **status** `string`
>
> Result status: `success` or `error`
>
> **message** `string`
>
> Human-readable description of the result
>
> **triggered\_flows** `integer`
>
> Number of automations triggered by this upload (based on your [Automations](/docs/automations.md) configuration).
>
> ### Example Response
>
> ```json theme={null}
> {
>   "status": "success",
>   "message": "App build uploaded successfully",
>   "triggered_flows": 3
> }
> ```
>
> ***
>
> ## Upload Workflow
>
> Here's the complete workflow for uploading a build via the API:
>
> **1. Start Upload**
>
> Call `/api/ci/start-upload` with your app details to get a presigned upload URL.
>
> **2. Upload File**
>
> PUT your build file (`.apk` for Android, `.zip` for iOS) to the presigned URL.
>
> **3. Confirm Upload**
>
> Call `/api/ci/confirm-upload` to finalize the upload and trigger automations.
>
> ### Build Requirements
>
> > [card] iOS Builds
> >
> > Upload a `.zip` file containing a simulator-compatible `.app` bundle. See [App Build Guide](/docs/app-build-guide.md) for details.
>
> > [card] Android Builds
> >
> > Upload a universal `.apk` file (not AAB). The APK must be compatible with `x86_64` emulators.
>
> ***
>
> ## Example: Upload from EAS Build Hooks
>
> If you use Expo EAS, you can upload to BugRadar directly from an [EAS build hook](https://docs.expo.dev/build-reference/npm-hooks/) instead of using the GitHub Action. This avoids keeping a GitHub Actions runner idle while waiting for the EAS build to finish, saving CI minutes.
>
> > [accordion] EAS build hook script and setup
> >
> > Create an `eas-build-on-success.sh` file in your project root (next to `package.json`). EAS automatically runs this script when a build completes successfully.
> >
> > > [!WARNING]
> > >
> > > Replace `com.example.myapp` with your bundle ID, `MyApp.app` with your `.app` bundle name, and `"My App"` with your app's display name.
> >
> > ```bash eas-build-on-success.sh theme={null}
> > #!/usr/bin/env bash
> > set -euo pipefail
> >
> > upload_to_BugRadar() {
> >   if [[ -z "${BugRadar_API_KEY:-}" ]]; then
> >     echo "BugRadar_API_KEY is not set, skipping upload."
> >     return 0
> >   fi
> >
> >   local platform="$EAS_BUILD_PLATFORM"
> >   local commit_sha="${EAS_BUILD_GIT_COMMIT_HASH:-unknown}"
> >   local branch_name="${EAS_BUILD_GIT_COMMIT_BRANCH:-}"
> >   local bundle_id="com.example.myapp"
> >   local app_name="My App"
> >   local repo_full_name="myorg/myrepo" # TODO: Replace with your org/repo
> >
> >   if [[ "$platform" == "ios" ]]; then
> >     local app_path
> >     app_path=$(find . -name "MyApp.app" -type d 2>/dev/null | head -1)
> >     if [[ -z "$app_path" ]]; then
> >       echo "Error: Could not find .app bundle"
> >       return 1
> >     fi
> >
> >     local filename="app-simulator.zip"
> >     local artifact="/tmp/${filename}"
> >     pushd "$(dirname "$app_path")"
> >     zip -r "$artifact" "$(basename "$app_path")"
> >     popd
> >   elif [[ "$platform" == "android" ]]; then
> >     local artifact
> >     artifact=$(find . -name "*.apk" -type f 2>/dev/null | head -1)
> >     if [[ -z "$artifact" ]]; then
> >       echo "Error: Could not find .apk file"
> >       return 1
> >     fi
> >     local filename=$(basename "$artifact")
> >   else
> >     echo "Unsupported platform: $platform"
> >     return 1
> >   fi
> >
> >   local start_response
> >   start_response=$(curl -sf -X POST https://backend.usebugradar.com/api/ci/start-upload \
> >     -H "X-API-Key: $BugRadar_API_KEY" \
> >     -H "Content-Type: application/json" \
> >     -d "{
> >       \"bundle_id\": \"$bundle_id\",
> >       \"platform\": \"$platform\",
> >       \"filename\": \"$filename\"
> >     }")
> >
> >   local upload_url file_path
> >   upload_url=$(echo "$start_response" | jq -r '.upload_url')
> >   file_path=$(echo "$start_response" | jq -r '.file_path')
> >
> >   if [[ -z "$upload_url" || "$upload_url" == "null" ]]; then
> >     echo "Error: Failed to get presigned URL"
> >     echo "Response: $start_response"
> >     return 1
> >   fi
> >
> >   if ! curl -sf -X PUT "$upload_url" \
> >     -H "Content-Type: application/octet-stream" \
> >     --data-binary "@$artifact"; then
> >     echo "Error: Failed to upload file to presigned URL"
> >     return 1
> >   fi
> >
> >   if ! curl -sf -X POST https://backend.usebugradar.com/api/ci/confirm-upload \
> >     -H "X-API-Key: $BugRadar_API_KEY" \
> >     -H "Content-Type: application/json" \
> >     -d "{
> >       \"bundle_id\": \"$bundle_id\",
> >       \"platform\": \"$platform\",
> >       \"uploaded_file_path\": \"$file_path\",
> >       \"name\": \"$app_name\",
> >       \"commit_sha\": \"$commit_sha\",
> >       \"branch_name\": \"$branch_name\",
> >       \"repo_full_name\": \"$repo_full_name\"
> >     }"; then
> >     echo "Error: Failed to confirm upload"
> >     return 1
> >   fi
> >
> >   echo "Uploaded to BugRadar successfully"
> > }
> >
> > upload_to_BugRadar || echo "Warning: BugRadar upload failed, continuing..."
> > ```
> >
> > Make the script executable and commit it to your repo:
> >
> > ```bash theme={null}
> > chmod +x eas-build-on-success.sh
> > ```
> >
> > Then add your API key as an EAS secret:
> >
> > ```bash theme={null}
> > eas secret:create --name BugRadar_API_KEY --value your-api-key-here --scope project
> > ```
> >
> > When you trigger a build (`eas build --platform ios --profile preview-simulator --non-interactive`), EAS runs the hook automatically after the build succeeds — no `--wait` flag or GitHub runner required.

> [tab] Web
>
> ## Upload Web Build
>
> Register a web app URL for testing. This endpoint creates or updates the app and creates a new build record.
>
> > [!NOTE]
> >
> > **POST** `/api/ci/upload-web-build` — Returns `200 OK`
>
> ### Request Body
>
> **app\_id** `string` *required*
>
> Unique identifier for your web app. Must be lowercase alphanumeric with hyphens only (e.g., `my-web-app`). This identifier is used to track your web app across deployments.
>
> **url** `string` *required*
>
> The URL to test. Must start with `http://` or `https://`. This is typically your preview deployment URL.
>
> **name** `string`
>
> Display name for your web app (e.g., "My Web App"). If the app already exists and the name differs, it will be updated.
>
> **environment** `string`
>
> Environment name to associate this app with (e.g., `staging`, `production`). Apps with the same app ID but different environments are treated as separate apps. Must match an existing environment in your organization. If omitted, the app is assigned to your default environment.
>
> **commit\_sha** `string`
>
> Git commit SHA for tracking which commit this build came from. Send the full 40-character SHA if you want runs of this build to [use your flows at its commit](/docs/api-runs.md#branch-builds-run-at-their-commit).
>
> **branch\_name** `string`
>
> Git branch name. Displayed in the BugRadar UI for build identification.
>
> **repo\_full\_name** `string`
>
> Repository name in `org/repo` format. Required for GitHub Check integration.
>
> **variables** `string | object`
>
> Key-value variables to attach to this build. Available in flow instructions via `${env:KEY}`. Accepts a string (`"KEY1=VALUE1,KEY2=VALUE2"`) or a JSON object (`{"KEY1": "VALUE1"}`). See [Build Variables](/docs/variables.md#build-variables).
>
> **location** `string`
>
> Optional. Two-letter ISO country code, such as `MX`. Every run this upload starts sends its browser traffic from that country. Web runs only. See [Proxy location](/docs/run-location.md).
>
> **locale** `string`
>
> Optional. Language and region, such as `de-DE`, that every run this upload starts opens the browser in. See [Language & region](/docs/language-and-region.md).
>
> ### Example Request
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/ci/upload-web-build \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "app_id": "my-web-app",
>     "url": "https://my-app-preview.vercel.app",
>     "name": "My Web App",
>     "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
>     "branch_name": "feature/new-login",
>     "repo_full_name": "myorg/myrepo",
>     "variables": {"PR_NUMBER": "42", "DEPLOY_URL": "https://pr-42.preview.app"}
>   }'
> ```
>
> ### Response Fields
>
> **status** `string`
>
> Result status: `success` or `error`
>
> **message** `string`
>
> Human-readable description of the result
>
> **app\_id** `string`
>
> The internal app ID (UUID) for the registered web app
>
> **build\_id** `string`
>
> The internal build ID (UUID) for this registration
>
> **triggered\_flows** `integer`
>
> Number of automations triggered (if no GitHub metadata provided)
>
> **github\_check\_runs** `string`
>
> Status of GitHub check runs: `pending` (if GitHub metadata provided)
>
> ### Example Response
>
> ```json theme={null}
> {
>   "status": "success",
>   "message": "Web URL registered successfully",
>   "app_id": "550e8400-e29b-41d4-a716-446655440000",
>   "build_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
>   "triggered_flows": 2
> }
> ```
>
> ### app\_id Format Requirements
>
> The `app_id` parameter must follow these rules:
>
> * Lowercase letters and numbers only
> * Hyphens allowed between words
> * No spaces, underscores, or special characters
> * Cannot start or end with a hyphen
> * Maximum 64 characters
>
> **Valid examples:** `my-web-app`, `staging`, `preview-app-123`, `frontend`
>
> **Invalid examples:** `My-Web-App`, `my_web_app`, `my web app`, `-my-app`

> [tab] Chrome Extension
>
> ## Upload an Extension Zip
>
> Use the normal two-step upload endpoints with
> `"platform": "chrome-extension"`. The build must be a `.zip` of an unpacked
> Manifest V3 extension. Extension apps are organization-wide and do not take an
> `environment`.
>
> ```bash theme={null}
> # 1. Request an upload URL
> curl -X POST https://backend.usebugradar.com/api/ci/start-upload \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "my-wallet-extension",
>     "platform": "chrome-extension",
>     "filename": "extension.zip",
>     "name": "My Wallet Extension"
>   }'
>
> # 2. PUT extension.zip to the returned upload_url
>
> # 3. Confirm the upload
> curl -X POST https://backend.usebugradar.com/api/ci/confirm-upload \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "my-wallet-extension",
>     "platform": "chrome-extension",
>     "uploaded_file_path": "FILE_PATH_FROM_STEP_1",
>     "name": "My Wallet Extension"
>   }'
> ```
>
> You can also snapshot a public Chrome Web Store extension without uploading a
> file:
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/ci/upload-extension-from-store \
>   -H "X-API-Key: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "store_url": "https://chromewebstore.google.com/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn",
>     "name": "MetaMask"
>   }'
> ```
>
> Limits: 500MB compressed, 2GB expanded, and 25,000 archive entries. Encrypted
> archives, symlinks, unsafe paths, and Manifest V2 are rejected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.