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.

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

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

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