TestFairy Documentation

About

This is the reference document 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 is easy, and can be done via command line with any programming language. Let's begin with a simple example. We will start by listing all our 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.)

curl -u "john@example.com:00001234cafecafe" "https://api.testfairy.com/api/1/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, please do not share it or post it on public code repositories or forums. To find your API key, please refer to your preferences page.

api/1/projects

Get all projects GET /api/1/projects/

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

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

api/1/projects/{project-id}/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 was either uploaded, or created by the TestFairy SDK.
Responses
STATUS 200 OK

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

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

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
STATUS 200 OK

{
    "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 have been 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
STATUS 200 OK

{
    "status": "ok"
}

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

Download the uploaded artifact GET /api/1/projects/{project-id}/builds/{build-id}/download/

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

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
STATUS 200 OK

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

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

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.

parameter	type	description
fields	string	Possible values: "meta", "logs", "events" Default value: "meta" Use "events" to load all events, screenshots, touches and other metrices. Use "logs" to fetch only logs. When loading logs, response will be application/text.

Responses
STATUS 200 OK

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

api/1/testers/

List all testers GET /api/1/testers/

List all testers in this account.
Responses
STATUS 200 OK

{
    "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.

parameter	type	description
email	string	One or more emails, separated by commas, to add to your account.
group	string	Assign tester or testers to this tester-group. Will create one if no such group exists. Default value: none
notify	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: off

Responses
STATUS 200 OK

{
    "status": "ok"
}

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

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

{
    "status": "ok"
}

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

Unblocks a single tester. Their invitations are restored. If the user is already unblocked, then nothing happens. Responses
STATUS 200 OK

{
    "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 were sent.
Responses
STATUS 200 OK

{
    "status": "ok"
}

api/1/feedbacks/

Get latest recorded feedbacks GET /api/1/feedbacks/

Get metadata for 100 of the latest feedbacks recorded.
Responses
STATUS 200 OK

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

api/1/audits/

Get recent audit trail items GET /api/1/audits/

Get recent audit trail items
Responses
STATUS 200 OK

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

api/1/cpanel/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
STATUS 200 OK

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

api/1/webhooks/

List all webhooks GET /api/1/webhooks/

List all webhooks in this account.
Responses
STATUS 200 OK

{
    "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 account.

parameter	type	description
webhook-name	string	Required. The name of the webhook.
webhook-url	string	Required. The url for the webhook.
webhook-status	string	Enables or disables the webhook, true or false. Default value: false
actions	string	Comma separated list of actions. options include crash feedback upload new-udid
webhook-project-ids	string	Optional. Comma separated list of project IDs.

Responses
STATUS 200 OK

{
    "status": "ok"
}

GET a single webhook GET /api/1/webhhook/{webhook-id}/

Returns a single webhook. Responses
STATUS 200 OK

{
    "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/webhhook/{webhook-id}/

Modifies a single webhook.

parameter	type	description
webhook-name	string	Required. The name of the webhook.
webhook-url	string	Required. The url for the webhook.
webhook-status	string	Enables or disables the webhook, true or false. Default value: false
actions	string	Comma separated list of actions. options include crash feedback upload new-udid
webhook-project-ids	string	Optional. Comma separated list of project IDs.

Responses
STATUS 200 OK

{
    "status": "ok"
}

Delete a webhook DELETE /api/1/webhhook/{webhook-id}/

Delete a single webhook.
Responses
STATUS 200 OK

{
    "status": "ok"
}

Last updated on 2023-05-23

Rest API

About

Getting Started