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/
Responses
200 | Success. |
{
"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/
Responses
200 | Success. |
{
"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}
Responses
200 | Success. |
{
"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}
Responses
200 | Success. |
{
"status": "ok"
}
Download the Uploaded Artifact
GET/api/1/projects/{project-id}/builds/{build-id}/download/
Responses
200 | Success. |
Invite Additional Testers to Build
POST/api/1/projects/{project-id}/builds/{build-id}/invites/
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 |
Responses
200 | Success. |
List All Recorded Sessions in Build
GET/api/1/projects/{project-id}/builds/{build-id}/sessions/
Responses
200 | Success. |
{
"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}
Parameters
fields | | OPTIONAL | STRING | Possible values: |
Responses
200 | Success. |
{
"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
Responses
200 | Success. |
{
"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/
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 |
Responses
200 | Success. |
{
"status": "ok"
}
Block a Tester
POST/api/1/testers/{tester-id}/block/
Responses
200 | Success. |
{
"status": "ok"
}
Unblock a Tester
DELETE/api/1/testers/{tester-id}/block/
Responses
200 | Success. |
{
"status": "ok"
}
Delete a Tester
DELETE/api/1/testers/{tester-id}
Responses
200 | Success. |
{
"status": "ok"
}
Feedbacks
Get Latest Recorded Feedbacks
GET/api/1/feedbacks/
Responses
200 | Success. |
{
"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
Responses
200 | Success. |
{
"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/
Responses
200 | Success. |
{
"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/
Responses
200 | Success. |
{
"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/
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: |
actions | | OPTIONAL | STRING | Comma separated list of actions. Options include: |
webhook-project-ids | | OPTIONAL | STRING | Comma separated list of project IDs. |
Responses
200 | Success. |
{
"status": "ok"
}
Get a Single Webhook
GET/api/1/webhook/{webhook-id}/
Responses
200 | Success. |
{
"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}/
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: |
actions | | OPTIONAL | STRING | Comma separated list of actions. Options include: |
webhook-project-ids | | OPTIONAL | STRING | Comma separated list of project IDs. |
Responses
200 | Success. |
{
"status": "ok"
}