Skip to main content

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​

The REST API supports two authentication methods:

MethodDocumentation
API KeyAPI Keys
OIDCOIDC Authentication

API Key (HTTP Basic Auth)​

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

OIDC (Bearer Token)​

curl -X GET "https://mobile.saucelabs.com/api/1/projects/" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-OIDC-Config-Key: <your-config-key>"

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

tip

For CI/CD automation, use service accounts.

API Endpoints​

Sauce Labs 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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
Sample Response
{
    "status": "ok"
}

Update a Specific Build​

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

Update editable fields of a specific build. Only the fields included in the request body are modified; omitted fields remain unchanged.Content Types: application/x-www-form-urlencoded or application/json. Note: multipart/form-data is not supported for this endpoint.

Parameters​

comment

| OPTIONAL | STRING |

Release notes / changelog for the build. Also accepted as changelog or release_notes.

tags

| OPTIONAL | STRING |

Comma-separated list of tags.

groups or app_permission_groups

| OPTIONAL | STRING |

Comma-separated list of tester group names. If present but empty, clears all groups. If omitted, groups are unchanged.

landing_page_mode

| OPTIONAL | STRING |

Landing page mode: open or closed.

metadata_*

| OPTIONAL | STRING |

Custom metadata fields. Use the prefix metadata_ followed by a key name (e.g. metadata_title, metadata_env).

Responses​

200Success.
Sample Request
curl -X PATCH \
  "https://mobile.saucelabs.com/api/1/projects/{project-id}/builds/{build-id}/" \
  -u "john@example.com:00001234cafecafe" \
  -d "comment=New release notes" \
  -d "tags=production,v2" \
  -d "groups=beta-testers,qa" \
  -d "landing_page_mode=open" \
  -d "metadata_title=My App Title"
Sample Response
{
    "status": "ok",
    "build_id": "8830728",
    "tags": ["production", "v2"],
    "metadata": {
        "title": "My App Title"
    },
    "changelog": "New release notes",
    "groups": ["beta-testers", "qa"],
    "landing_page_mode": "open"
}

Error Codes​

1Missing or invalid build-id.
99No permissions — the authenticated user does not have write access to this project.
133Tester accounts cannot update builds.
156Cannot set landing_page_mode to open when login is required by the account settings.

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​

200Success.
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​

200Success.

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​

200Success.

Testers​

List All Testers​

GET/api/1/testers

List all testers in this account.

Query Parameters​

buildId

| OPTIONAL | INTEGER |

When provided, each tester includes build-specific fields: isInvitedToBuild, buildInviteStatus, buildInviteTime, and appDownloadLink.

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "testers": [
        {
            "email": "james@example.com",
            "groups": [{
                "id": 100,
                "name": "friends"
            }],
            "lastLogin": "2025-11-20 14:30:00",
            "createdAt": "2024-06-15 09:00:00"
        },
        {
            "email": "alice@testfairy.com",
            "groups": [{
                "id": 100,
                "name": "friends"
            }, {
                "id": 200,
                "name": "family"
            }],
            "lastLogin": "2026-01-10 08:45:00",
            "createdAt": "2024-03-22 11:30:00"
        }
    ]
}

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​

200Success.
Sample Response
{
    "status": "ok"
}

Get a Single Tester​

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

Get details for a single tester by ID.

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "tester": {
        "id": 123,
        "email": "james@example.com",
        "isBlocked": false,
        "groups": [{
            "id": 100,
            "name": "friends"
        }],
        "lastLogin": "2025-11-20 14:30:00",
        "createdAt": "2024-06-15 09:00:00"
    }
}

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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
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​

200Success.
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 (Deprecated)​

Deprecated

This endpoint is deprecated. Use the v2 audit endpoints below instead: /api/2/audits/, /api/2/audits/admin-trail/, /api/2/audits/tester-trail/.

GET/api/1/audits

Get recent audit trail items.

Responses​

200Success.
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
            }
        }
    ]
}

Get All Audit Logs​

GET/api/2/audits/

Get paginated audit logs across all action types. Returns admin trail, tester trail, and all other audit events. Requires admin permissions with all-projects access.For multi-site accounts, account managers see logs across all related sites. Admins see logs for their own site only.

Query Parameters​

sitestring or intOptional. Multi-site accounts only. Filter by site subdomain (e.g. site-1) or enterprise ID (e.g. 456). Must be within the caller's accessible sites.
action_typeintOptional. Filter by a specific action type ID.
start_datestringOptional. Filter from date (format: YYYY-MM-DD).
end_datestringOptional. Filter to date (format: YYYY-MM-DD).
pageintPage number (default: 1).
per_pageintResults per page (default: 50, max: 200).

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "audits": [
        {
            "id": 789,
            "timestamp": "2026-03-01 09:00:00",
            "enterpriseId": 456,
            "siteName": "My Organization",
            "userId": 789,
            "userEmail": "admin@example.com",
            "ipAddress": "1.2.3.4",
            "actionType": 1905,
            "actionLabel": "Security settings changed",
            "actionData": {
                "from": {"mfa_enabled": false},
                "to": {"mfa_enabled": true}
            }
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 315,
        "total_pages": 7
    }
}

Get Admin Trail Audit Logs​

GET/api/2/audits/admin-trail/

Get paginated admin trail audit logs, including security changes, integration updates, team management actions, and webhook modifications. Requires admin permissions with all-projects access.For multi-site accounts, account managers see logs across all related sites. Admins see logs for their own site only.

Query Parameters​

sitestring or intOptional. Multi-site accounts only. Filter by site subdomain (e.g. site-1) or enterprise ID (e.g. 456). Must be within the caller's accessible sites.
action_typeintOptional. Filter by a specific action type ID.
start_datestringOptional. Filter from date (format: YYYY-MM-DD).
end_datestringOptional. Filter to date (format: YYYY-MM-DD).
pageintPage number (default: 1).
per_pageintResults per page (default: 50, max: 200).

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "audits": [
        {
            "id": 123,
            "timestamp": "2026-02-25 10:30:00",
            "enterpriseId": 456,
            "siteName": "My Organization",
            "userId": 789,
            "userEmail": "admin@example.com",
            "ipAddress": "1.2.3.4",
            "actionType": 1905,
            "actionLabel": "Security settings changed",
            "actionData": {
                "from": {"mfa_enabled": false},
                "to": {"mfa_enabled": true}
            }
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 230,
        "total_pages": 5
    }
}

Get Tester Trail Audit Logs​

GET/api/2/audits/tester-trail/

Get paginated tester trail audit logs, including tester invitations, deletions, group assignments, and build distribution changes. Requires admin permissions with all-projects access.For multi-site accounts, account managers see logs across all related sites. Admins see logs for their own site only.

Query Parameters​

sitestring or intOptional. Multi-site accounts only. Filter by site subdomain (e.g. site-1) or enterprise ID (e.g. 456). Must be within the caller's accessible sites.
action_typeintOptional. Filter by a specific action type ID.
start_datestringOptional. Filter from date (format: YYYY-MM-DD).
end_datestringOptional. Filter to date (format: YYYY-MM-DD).
pageintPage number (default: 1).
per_pageintResults per page (default: 50, max: 200).

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "audits": [
        {
            "id": 456,
            "timestamp": "2026-02-25 14:15:00",
            "enterpriseId": 456,
            "siteName": "My Organization",
            "userId": 789,
            "userEmail": "admin@example.com",
            "ipAddress": "1.2.3.4",
            "actionType": 1200,
            "actionLabel": "Invited testers",
            "actionData": {
                "emails": ["tester1@example.com", "tester2@example.com"]
            }
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 85,
        "total_pages": 2
    }
}

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​

200Success.
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​

200Success.
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​

200Success.
Sample Response
{
    "status": "ok"
}

Get a Single Webhook​

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

Returns a single webhook.

Responses​

200Success.
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​

200Success.
Sample Response
{
    "status": "ok"
}

Delete a Webhook​

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

Deletes a single webhook.

Responses​

200Success.
Sample Response
{
    "status": "ok"
}

Sites​

List All Sites​

GET/api/1/site/

List all sites in this account.

Responses​

200Success.
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​

200Success.
Sample Response
{
    "status": "ok"
}

Delete a Site​

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

Deletes an account .

Responses​

200Success.
Sample Response
{
    "status": "ok"
}