REST API

In this document you can find the reference for the Sauce Labs Mobile App Distribution REST API. This API allows the developer to access and interact with Sauce Labs Mobile App Distribution data remotely.

Authentication

All REST API requests require authentication using HTTP Basic Authentication with your email address and API key.

API Key Overview

Your API key is a unique credential that authenticates your API requests. It is not your account password.

Important Security Guidelines

• Your API key is private - Do not share it or post it on public code repositories or forums.
• Use service accounts for automation - Create dedicated service accounts for CI/CD pipelines and automated processes.
• Never use Site Manager accounts for API calls - Site Manager accounts have elevated privileges that are inappropriate for automated API access. Always use a dedicated service account with appropriate permissions.

Finding Your API Key

1. Log in to your Sauce Labs Mobile App Distribution account.
2. Navigate to Account > Settings.
3. Locate the Access Key section.
4. Copy your username and API key.

For detailed guidance on creating service accounts, managing API keys, and security best practices, see Service Accounts and API Keys.

Authentication Format

Use HTTP Basic Authentication with your email as the username and your API key as the password:

curl -u "email:api-key" "https://mobile.saucelabs.com/api/1/endpoint"

API Endpoints

Sauce Mobile App Distribution REST API is available at the following endpoints:

US-East-1 (Primary)

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

EU-Central-1

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

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://api.testfairy.com/api/1/

Getting Started

Getting started with the REST API can be done via the command line with any programming language. Let's begin with an example: by listing all our projects.

Example: List All Projects

US-East-1:

curl -u "john@example.com:00001234cafecafe" "https://mobile.saucelabs.com/api/1/projects/"

EU-Central-1:

curl -u "john@example.com:coffee00001234" "https://mobile.eu-central-1.saucelabs.com/api/1/projects/"

A project is either an iOS app or an Android app (two apps with the same package name but on different platforms are considered two projects.)

In the example above, the user is john@example.com and the API key is 0001234cafecafe. This authentication is required for all requests to the REST server.

Projects

Get All Projects

GET/api/1/projects/

Returns a list of all projects (iOS and Android apps) in this account.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "projects": [
        {
            "id": "6905338",
            "self": "/projects/19-groupshot",
            "name":"GroupShot",
            "packageName":"com.groupshot",
            "platform":"Android",
            "icon":"[URL TO APP ICON]",
            "landingPageMode": "open"
        }
    ]
}

Builds

Get All Builds in a Project

GET/api/1/projects/{project-id}/builds/

Get all builds in a specific project. Each build is a distinct version that is either uploaded or created by the Sauce Labs Mobile App Distribution SDK.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "builds": [
        {
            "id":"8830728",
            "self":"/projects/6806100-myapplication/builds/8830728",
            "projectId":"6806100",
            "appName":"My Application",
            "appVersion":"DemoApp",
            "appVersionCode":"20",
            "appDisplayName":"My Application - DemoApp (20)",
            "iconUrl":"[APP ICON URL]",
            "appUrl":"[URL TO APK OR IPA FILE]",
            "landingPageMode": "closed",
            "sessions":6,
            "crashes":0,
            "testers":0,
            "feedbacks":0,
            "downloads":1,
            "uploadedAt":"2019-04-04 16:03:15",
            "uploadedVia":"[UPLOAD DETAILS]",
            "hasTestFairySdk":true,
            "insightsEnabled":true,
            "videoEnabled":true
        }
    ]
}

---

Get Metadata for a Specific Build

GET/api/1/projects/{project-id}/builds/{build-id}

Get a specific build of a specific project. Query the /api/1/projects/{project-id} API for a list of available builds.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "build": {
        "id":"8830728",
        "self":"/projects/6806100-myapplication/builds/8830728",
        "projectId":"6806100",
        "appName":"My Application",
        "appVersion":"DemoApp",
        "appVersionCode":"20",
        "appDisplayName":"My Application - DemoApp (20)",
        "iconUrl":"[APP ICON URL]",
        "appUrl":"[URL TO APK OR IPA FILE]",
        "landingPageMode": "closed",
        "sessions":6,
        "crashes":0,
        "testers":0,
        "feedbacks":0,
        "downloads":1,
        "uploadedAt":"2019-04-04 16:03:15",
        "uploadedVia":"[UPLOAD DETAILS]",
        "hasTestFairySdk":true,
        "insightsEnabled":true,
        "videoEnabled":true
    }
}

---

Delete a Specific Build

DELETE/api/1/projects/{project-id}/builds/{build-id}

Delete a specific build. When all builds of a project are deleted, the project itself is removed from /api/1/projects API. When deleting a build, all of its artifacts (IPA/APK files), recorded sessions, and crashes are also deleted.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Copy a Specific Build to a Folder

POST/api/1/projects/{project-id}/builds/{build-id}/copy

Use this endpoint to copy a specific build to a specified folder. You can either create a new folder or copy the build to an existing one.

Parameters

folder_name	| REQUIRED | STRING | The name or path of the target folder. Examples: Folder1 or /Project1/Folder1.
app_name	| OPTIONAL | STRING | Defines a new name for the application when copying the build to the target folder. If specified, the build is renamed to the given app_name. If not specified, the original application name is preserved.
groups	| OPTIONAL | STRING | A comma-separated list of tester group names or IDs for the build. If not specified, the original assigned groups will be copied over to the build.
projectGroups	| OPTIONAL | STRING | A comma-separated list of tester group names or IDs for the project. If not specified, the original assigned groups will be copied over to the project.
allowAllTesters	| OPTIONAL | BOOLEAN | Value 1 allows all other users to access the copied build, while 0 prevents access. If not specified, the original assigned value will be copied over to the project.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "build_id": "1000",
    "folder_path": "/Project1/Folder1",
    "app_name": "My Application",
    "assigned_groups": [
      "13",
      "group14",
      "12"
    ],
    "invalid_groups": [
      "abcd",
      "efgd"
    ],
    "assigned_project_groups": [
      "group13",
      "14",
      "12"
    ],
    "invalid_project_groups": [
      "abcd",
      "efgd"
    ]
}

---

Download the Uploaded Artifact

GET/api/1/projects/{project-id}/builds/{build-id}/download/

Downloads the binary file uploaded to Sauce Labs Mobile App Distribution.

Responses

200

Success.

---

Invite Additional Testers to Build

POST/api/1/projects/{project-id}/builds/{build-id}/invites/

Invite one or more tester groups to this specific build. You can optionally send out an email.

Parameters

groups	| REQUIRED | STRING | A comma-separated list of tester group names or IDs.
comment	| OPTIONAL | STRING | Additional text that will be added to the email, such as release notes.
notify	| OPTIONAL | STRING | INTEGER Pass notify=on or notify=1 to send out an email to each tester. By default, email sending is disabled.

Responses

200

Success.

Testers

List All Testers

GET/api/1/testers

List all testers in this account.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "testers": [
        {
            "email":"james@example.com",
            "groups":[{
                id: 100,
                name: "friends"
            }]
        },
        {
            "email":"alice@testfairy.com",
            "groups":[{
                id: 100,
                name: "friends"
            }, {
                id: 200,
                name: "family"
            }]
        }
    ]
}

---

Add a New Tester

POST/api/1/testers/

Add a new tester to account. Optionally can add them to a group.

Parameters

email	| OPTIONAL | STRING | One or more emails, separated by commas, to add to your account.
group	| OPTIONAL | STRING | Assign tester or testers to this tester-group. It creates one if no such group exists. Default value: none.
notify	| OPTIONAL | STRING | INTEGER Pass notify=on or notify=1 to send a welcome email when inviting this tester. The email will use the "Tester Welcome Email" template, which can be customized. By default, email sending is disabled.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Block a Tester

POST/api/1/testers/{tester-id}/block/

Blocks a single tester. They cannot download the apps they are invited to. However, the data stays. You can later unblock this tester or delete them completely.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Unblock a Tester

DELETE/api/1/testers/{tester-id}/block/

Unblock a single tester. Their invitations are restored. If the user is already unblocked, then nothing happens.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Delete a Tester

DELETE/api/1/testers/{tester-id}

Delete a single tester, remove them from any tester-groups they might be in, and invalidate all invitations that are sent.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Add a Tester to a Group

POST/api/1/testers/groups/{group-id}

Add a single or multiple testers to a specific group.

Parameters

email

| REQUIRED | STRING | One or more email addresses, separated by commas, to be added to a group.

Responses

200

Success.

Sample Response

{
  "status": "ok",
  "testers": [
    {
      "email": "tester1@saucelabs.com"
    },
    {
      "email": "tester2@saucelabs.com"
    }
  ]
}

---

Remove a Tester from a Group

DELETE/api/1/testers/groups/{group-id}

Remove a single or multiple testers from a specific group.

Note: Groups without any members will be discarded.

Parameters

email

| REQUIRED | STRING | One or more email addresses, separated by commas, to be removed from a group.

Responses

200

Success.

Sample Response

{
  "status": "ok",
  "testers": [
    {
      "email": "tester1@saucelabs.com"
    },
    {
      "email": "tester2@saucelabs.com"
    }
  ]
}

---

List All Tester groups

GET/api/1/testers/groups

List all tester groups in this account.

Responses

200

Success.

Sample Response

{
  "status": "ok",
  "groups": [
    {
      "id": 14,
      "name": "group1",
      "testers": [
        [
          {
            "email": "tester1@saucelabs.com"
          },
          {
            "email": "tester2@saucelabs.com"
          },
          {
            "email": "tester3@saucelabs.com"
          }
        ]
      ]
    },
    {
      "id": 39,
      "name": "group2",
      "testers": [
        [
          {
            "email": "tester1@saucelabs.com"
          }
        ]
      ]
    }
  ]
}

---

Create a Tester Group

POST/api/1/testers/groups

Create a new tester group

Parameters

groupName

| REQUIRED | STRING | Specify a group name.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "id": "40",
    "name": "group3"
}

---

Feedbacks

Get Latest Recorded Feedbacks

GET/api/1/feedbacks/

Get metadata for 100 of the latest feedbacks recorded.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "feedbacks": [
        {
            "recorded_at": "2018-08-01 04:14:46",
            "text": "Feedback working",
            "feedbackId": "54321",
            "screenshotUrl": "https://s3.amazonaws.com/feedback.jpg",
            "buildId": "1234",
            "projectId": "23456",
            "recordedAt":"2018-08-01 14:14:46",
            "source": "shake",
            "reported_by": "john@testfairy.com",
            "session_id": "8765432"
        }
    ]
}

Audits

Get Recent Audit Trail Items

GET/api/1/audits

Get recent audit trail items.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "audits": [
        {
            "id": 23534603,
            "timestamp": "2020-04-21 02:31:54",
            "ipAddress": "54.235.41.91",
            "eventType": "download_app",
            "eventData": {
                "projectId": 6833287,
                "buildId": 9087976,
                "appName": "MyApp",
                "appVersion": "1.0 (10)",
                "testerEmail": "john@example.com",
                "filesize": 31348
            }
        }
    ]
}

Permissions

Get the List of Admins and Their Permissions

GET/api/1/cpanel/permissions/

Get the list of admins in the account and their permissions.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    admins:
    [
        {
            email: "joe@example.com",
            role: "account-owner",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "bob@example.com",
            role: "account-manager",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "alice@example.com",
            role: "admin",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "michael@example.com",
            role: "admin",
            permissions: [
                "16527:rw",
                "16517:rw",
                "69237:r"
            ]
        },
    ]
}

Webhooks

List All Webhooks

GET/api/1/webhooks/

List all webhooks in this account.

Responses

200

Success.

Sample Response

{
    "status":"ok",
    "webhooks":[
        {
            "id":12,
            "status":"0",
            "name":"Slack Webhook @vijay",
            "url":"https://hooks.slack.com/services/",
            "actions":"crash,feedback,upload,new-udid",
            "projectIds":"12345,45643"
        }
    ]
}

---

Add a New Webhook

POST/api/1/webhook/

Add a new webhook to the account.

Parameters

webhook-name	| REQUIRED | STRING | The name of the webhook.
webhook-url	| REQUIRED | STRING | The URL for the webhook.
webhook-status	| OPTIONAL | STRING | Enables or disables the webhook. The values are: true, false. Default value is false.
actions	| OPTIONAL | STRING | Comma separated list of actions. Options include: crash, feedback, upload, new-udid.
webhook-project-ids	| OPTIONAL | STRING | Comma separated list of project IDs.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Get a Single Webhook

GET/api/1/webhook/{webhook-id}/

Returns a single webhook.

Responses

200

Success.

Sample Response

{
    "status": "ok",
    "webhook": {
        "id":12,
        "status":"0",
        "name":"Slack Webhook @vijay",
        "url":"https://hooks.slack.com/services/",
        "actions":"crash,feedback,upload,new-udid",
        "projectIds":"12345,45643"
    }
}

---

Modify a Webhook

POST/api/1/webhook/{webhook-id}/

Modifies a single webhook.

Parameters

webhook-name	| REQUIRED | STRING | The name of the webhook.
webhook-url	| REQUIRED | STRING | The URL for the webhook.
webhook-status	| OPTIONAL | STRING | Enables or disables the webhook. The values are: true, false. Default value is false.
actions	| OPTIONAL | STRING | Comma separated list of actions. Options include: crash, feedback, upload, new-udid.
webhook-project-ids	| OPTIONAL | STRING | Comma separated list of project IDs.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Delete a Webhook

DELETE/api/1/webhook/{webhook-id}/

Deletes a single webhook.

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

Sites

List All Sites

GET/api/1/site/

List all sites in this account.

Responses

200

Success.

Sample Response

{
  "status": "ok",
  "site": {
    "accounts": [
      {
        "id": "1",
        "name": "Site 1",
        "buildsCount": 0,
        "users": [
          {
            "email": "[site-subaccount-682ae46476f9f]",
            "role": "Account Owner"
          },
          {
            "email": "sitemanager@saucelabs.com",
            "role": "Account Manager"
          }
        ]
      }
    ],
    "managers": [
      {
        "email": "accountmanager@saucelabs.com"
      }
    ]
  }
}

---

Create a New Site

POST/api/1/site/

Add a new site to the organization.

Parameters

name	| REQUIRED | STRING | The name of the account. The string accepts numbers, letters, -, and _. The length has to be more than 3 characters.
loginMethod	| OPTIONAL | STRING | Specify how users can log in to account. Pass 0 for SSO or 1 for credentials

Responses

200

Success.

Sample Response

{
    "status": "ok"
}

---

Delete a Site

DELETE/api/1/site/{site-id}/

Deletes an account .

Responses

200

Success.

Sample Response

{
    "status": "ok"
}