Upload API

Streamline your build process and upload APKs or IPAs directly to Sauce Labs Mobile App Distribution.

Authentication

The Upload API supports two authentication methods:

Method	Documentation
API Key	API Keys
OIDC	OIDC Authentication

API Key (Form Parameter)

curl https://app.testfairy.com/api/upload -F api_key='your_api_key' -F file=@app.apk

OIDC (Bearer Token)

curl -X POST https://mobile.saucelabs.com/api/upload/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-OIDC-Config-Key: <your-config-key>" \
  -F "file=@app.apk"

See OIDC Authentication: API Usage for setup and token retrieval.

tip

For CI/CD automation, use service accounts.

API Endpoints

The Upload API is available at the following endpoints:

US-East-1 (Primary)

https://mobile.saucelabs.com/api/upload/

EU-Central-1

https://mobile.eu-central-1.saucelabs.com/api/upload/

note

Access keys are different in each Data Center. Ensure you are using the correct API key for the data center you are accessing.

Legacy Endpoint (US-East)

The previous TestFairy endpoint remains available:

https://app.testfairy.com/api/upload/

Usage

Gradle

fastlane

CircleCI

Bitrise

NetBeans

TeamCity

GitLab

Upload API

POST/api/upload/

Parameters

api_key	| REQUIRED for API Key auth | Your API application key. Required when using API key authentication; omit when using OIDC. See API Keys for details.
file	| REQUIRED | Android Package Kit (APK), Android App Bundle (AAB), iOS package App Store (IPA), or ZIP (MacOS) file data.
app_name	| OPTIONAL | Use this parameter to customize the app name displayed on the dashboard. Note: If not provided, the app name will be automatically extracted from the uploaded file. To change the app name before uploading, see the App Versioning: Display Name documentation.
symbols_file	| OPTIONAL | Symbols mapping file. For iOS, this is a path to the zipped symbols file (dSYM). For Android, this is the path to the .txt file
groups	| OPTIONAL | Comma-separated list of tester groups that get permission to download this app.
notify	| OPTIONAL | Send email to all users in 'groups'. It can be on or off. Default is off.
release_notes	| OPTIONAL | Release notes for this upload. This text adds to emails and landing pages.
auto_update	| OPTIONAL | Allows to upgrade all users to the current version. It can be on or off. Default is off.
tags	| OPTIONAL | Set of comma-separated tags to be displayed and searched upon.
folder_name	| OPTIONAL | Name of the dashboard folder that contains this app
landing_page_mode	| OPTIONAL | Landing page mode. It can be open or closed. Default is open.
upload_to_saucelabs	| OPTIONAL | Upload file directly to Sauce Labs. It can be on or off. Default is off.
platform	| OPTIONAL | In case the app is not iOS or Android, which are detected automatically, use this to mark an app for specific desktop or console platforms. Values can be "Xbox", "PlayStation", "switch", "windows", "macos". This feature is not enabled by default. Contact support for more information.

Required Params

Sample Request with Required Params

curl https://app.testfairy.com/api/upload -F api_key='your_api_key' -F file=@sample.apk

Optional Params

Sample Request with Optional Params

curl https://app.testfairy.com/api/upload \
 -F api_key='your_api_key' \
 -F file=@sample.apk \
 -F symbols_file=@sample_mapping.txt \
 -F groups='friends,beta' \
 -F notify='on' \
 -F release_notes='stabilitty fixes, improvement in ui' \
 -F tags='production, english'

Responses

In the case of an error, Sauce Labs Mobile App Distribution returns a JSON with status => fail and code with one of the values listed below. Sauce Labs Mobile App Distribution supplies an additional human-readable error message to detail the cause of the specific error.

200	Success.
1	Parameter 'xxx' is missing.
5	Invalid API key.
105	Invalid file.

Sample Response

{
    "status": "ok",
    "build_id": "106410",
    "project_id": "61545",
    "app_name": "My Demo App",
    "app_version": "2.0.2",
    "file_size": 2319620,
    "build_url": "https://app.testfairy.com/projects/61545/builds/106410",
    "download_page_url": "https://tsfr.io/31thr2",
    "app_url": "https://app.testfairy.com/download/64R3CE1R6GRK0B9AXMCY77GJWBAW5K7XYV8K0T0CW/getapp",
    "invite_testers_url": "https://app.testfairy.com/projects/61545/builds/106410/invite",
    "icon_url": "https://s3.amazonaws.com/testfairy/icons/876033/230c74eece00376eb476516755.png",
    "options": "video-quality=medium,screenshot-interval=1,session-length=60m,video,logcat,shake,cpu,memory,phone-signal,battery,wifi",
    "platform": "iOS",
    "tags": [],
    "metadata": [],
    "has_testfairy_sdk": true,
    "symbols_download_url": "https://app.testfairy.com/api/1/projects/61545/builds/106410/symbols/download/",
    "attachments": null,
    "landing_page_url": "https://app.testfairy.com/join/31thr2",
    "build_specific_landing_page_url": "https://app.testfairy.com/join/31thr2?id=106410",
    "landing_page_mode": "closed"
}

Can I Add Custom Metadata?

Yes. Any POST parameter prefixed with "metadata." in the name is considered custom data and stored along with the upload. For example, consider this command:

curl https://app.testfairy.com/api/upload \
 -F api_key='your_api_key' \
 -F file=@sample.apk \
 -F metadata.branch=master \
 -F metadata.locale=us-en

Metadata is displayed and can be searched on in App Versions page by clicking on an app from the Dashboard. You can also view them on a single version's settings page.

Can I attach the symbols file to my app to download it later?

Yes! You can attach your dSYM zipped for iOS / Text file .txt for Android app while uploading the app. Check out the Upload/Download Symbols file documentation for more details.