Skip to main content

REST API

In this document you can find the reference for the TestFairy REST API. This API allows the developer to access and interact with TestFairy data remotely.

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.

Supported Public Cloud endpoints:

US-East-1​

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

EU-Central-1 (Access keys are different in each Data Center)​

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

Previous TestFairy US-East endpoint:​

curl -u "john@example.com:00001234cafecafe" "https://api.testfairy.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, you can see that our user is john@example.com and the API key is 0001234cafecafe. This user authentication token is required for all requests to the REST server.

Your API key is private, do not share it or post it on public code repositories or forums. To find your API key, refer to your preferences page.

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]"
        }
    ]
}

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 TestFairy 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]",
            "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]",
        "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"
}

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.

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "build_id": "1000",
    "folder_path": "/Project1/Folder1"
}

Download the Uploaded Artifact​

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

Downloads the binary file uploaded to TestFairy.

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 |

Comma separated list of tester group names or id.

comment

| OPTIONAL | STRING |

Additional text that will be added to the email, such as release notes.

notify

| OPTIONAL | STRING |

Set to on to send out an email to each tester. Default value is off.

Responses​

200Success.

List All Recorded Sessions in Build​

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

Get metadata for all sessions recorded for a specific build.

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "sessions": [
        {
            "id": 1,
            "self": "/projects/2197059-demoapp/builds/4867553/sessions/1",
            "startTime": "2017-01-22 16:42:40",
            "duration": "15:01",
            "testerEmail": "john@testfairy.com",
            "device": "Samsung - Samsung Galaxy S8",
            "ipAddress": "23.100.122.175",
            "crashed": false,
            "countryName": "United States",
            "countryCode": "us"
        }
    ]
}

Get Session Data, Events and Logs​

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

Get metadata (and optionally data) for a specific session.

Parameters​

fields

| OPTIONAL | STRING |

Possible values: meta, logs, events. The default value is meta. Use events to load all events, screenshots, touches, and other metrics. Use logs to fetch only logs. When loading logs, the response is application/text.

Responses​

200Success.
Sample Response
{
    "status": "ok",
    "session": {
        "id":4426273741,
        "sessionStartTime":"2019-05-20 09:05:30",
        "duration":"00:27",
        "testerEmail":"blabla@ex.com",
        "device":"Xiaomi - Redmi S2",
        "ipAddress":"84.94.200.136",
        "crashed":false,
        "identity":{
            "correlationId":"blabla@ex.com",
            "attr3":"three",
            "attr4":"four",
            "attr1":"High",
            "attr2":"1.0",
            "attr5":"Version 1.0"
    }
}

Testers​

List All Testers​

GET/api/1/testers

List all testers in this account.

Responses​

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

Pass notify=on to send out a welcome email when inviting this tester. The email sent is the "Tester Welcome Email" template and can be configured. Default value is off.

Responses​

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

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​

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
            }
        }
    ]
}

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"
}